legacy.manage_subscriber

Description

WARNING: This method may be combined with other method calls within the same POST command as described in calling an API method. However, it is not advisable to do so.

Use this method to

• add a new subscriber contact record
• update an existing subscriber contact record
• unsubscribe a contact record
• delete a contact record

You can also use this method to post a Refer-a-Friend conversion. To do so, you must send two Refer a Friend specific variables when a referred user signs up for the FIRST time (updating their profile will not update as a conversion stat):

Set your sign up link in the Refer a Friend email to pass through "ref" and "select" query string parameters to the page the user clicks when they want to sign up.

Example URL:

http://www.example.com/signup_form.htm?ref=%%ref_id%%&select=<some_program_id>

Then, when the user clicks the link to the signup form from the Refer a Friend email, the sign up page needs to pass along the select and ref values from the original link (noted above) back to our API with the user data in order to track the conversion.

Arguments

Field	Description	Field Type	Required	Example
email	The email address of the subscriber	string 132 characters max.	Conditional; email is only required if external_id is not included in the call	jsmith@example.com
external_id	A subscriber's identifier defined within an external system. This ID must be unique across all subscribers.	string 64 characters max.	No	ABC123DEF456
newemail	The email address used if replacing the current email address	string 132 characters max.	No	j_smith@Mapp.com
new_external_id	The external system's identifier for the subscriber that is replacing the current one	string 64 characters max.	No	ABC123DEF456
firstname	The subscriber's first name (64 characters max)	string	No	John
lastname	The subscriber's last name (64 characters max)	string	No	Smith
address	Street address (60 characters max)	string	No	123 Main St.
city	City name (64 characters max)	string	No	San Diego
state	State or province (64 characters max)	string	No	CA
postal_code	Postal code (64 characters max)	string	No	92110
country	Country name or ISO code (64 characters max)	string	No	US
phone_hm	Home phone number (64 characters max)	string	No	619-295-1856
phone_wk	Work phone number (64 characters max)	string	No	619-295-1856
fax	Fax number (64 characters max)	string	No	619-295-1856
email_type	A one-letter code defining the subscriber's email preference as: P – plain text H – HTML N – No preference	string	No	H
welcome_trigger	The value used to trigger a specific welcome message. The custom field specifically used as the Welcome Message Trigger Field is automatically mapped to this element.	string	No	website
doi	Applies only to new subscriber records. Specifies whether to send the new subscriber a standard Opt-in Confirmation email. Only when the message recipient confirms will the record be marked as a subscriber. 0 – follow the account default setting for Double Opt-in (default) 1 – send the Double Opt-in email regardless of the account's default setting	boolean	No	1
welcomeletter	Applies only to new subscriber records. Specifies whether to send the new subscriber a welcome letter. If <doi>1</doi> is also in the input parameter, the subscriber will receive the Welcome letter after confirming the double opt-in request. 0 – do not send a welcome letter (default) 1 – send a welcome letter	boolean	No	1
custvalNNNN	A custom field that exists within the system where NNNN is the custom field ID to be referenced. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Assets > Manage Custom Fields. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID.	string, date, or number. If date, must be in the format YYYY-MM-DD. If number, must be either of the following characters: 0-9 . + –	No	Fido
grp	A comma delimited list of the ID numbers of the static segments to which this subscriber should be added as a member. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Segmentation > Manage Static Segments. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID.	string	No	342234,13212,​64533,7788
grpreplace	Specifies whether you want to change any of the subscriber's static segment memberships. 0 – do not replace (default) 1 – replace the subscriber's existing static segment memberships with the ones specified in the <grp> element. If the <grp> element is empty, then the system will remove this subscriber from all current static segments.	boolean	No	1
grpremove	A comma delimited list of the ID numbers of the static segments from which this subscriber should be removed. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Segmentation > Manage Static Segments. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID.	string	No	342231,13211,​64531,7781
signup_page	The URL of the page where the subscriber signed up	string	No	http://signup.bh.com/​signup.htm
subscriber_ip	The subscriber's ip address	string	No	66.185.166.116
select	ID of Refer-A-Friend program to use. To find the Refer-a-Friend program ID, log in to the application and navigate to Subscribers > Refer A Friend > Edit Refer A Friend. Select a specific Refer-a-Friend program and click the [Edit] button. When the screen appears, look in the URL bar of your browser. The program ID will be the last sequence of digits in the URI.	string	No	52927 From the URL https://barnstormer.​buffalobarn.com/​Empower/referafriend/​edit/52927
refer{N}	Up to 10 email addresses can be passed where: <refer1>, <refer2>, <refer3>, etc.	string	No	john_doe@example.com
name{N}	Up to 10 names of referred subscribers. The numerical pattern of the names must correspond to the pattern of the email addresses passed in the <refer{N}> element (see above).	string	Yes if <select> is included in the POST.	John or John Doe
personalized_message{N}	A personal message provided by the referring subscriber that will be included in the refer-a-friend message. The numerical pattern of the message must correspond to the pattern of the email addresses passed in the <refer{N}> element (see above).	string	No	Hey Joe, check out this awesome email list.
ref	The internal contact_id of the referring subscriber. You must set up the Refer a Friend email in your system to send this value using the tag %%ref_id%%. This will be dynamically set when the email is sent.	number	No	11209893
fmid	The internal contact_id of the subscriber who forwarded a message to the subscriber signing up	number	No	84723024
remove	Specifies whether to remove a subscriber contact record from the system. 0 – do not remove (default) 1 – remove from system. NOTE: this performs a subscriber delete, not simply an opt-out. Contact records that are deleted through the use of this input parameter will be added back to the database as active records when included in files that are imported either via the Legacy.bulk_sync API method call or from directly within the application.	boolean	No	1
optout	Specifies whether to unsubscribe a contact record from receiving further email marketing communications. 0 – do not unsubscribe (default) 1 – unsubscribe the contact record	boolean	No	1
check_optout	Specifies whether to check if a contact record has previously opted out. 0 – do not check if the contact record has previously opted out (default) 1 – do check if a contact record has previously opted out. If <check_optout>1</check_optout> is included as an input parameter and the subscriber has previously opted out, the subscriber will not be added back into the system.	number	No	1
message_hash	If <optout>1</optout> is included as an input parameter, this will tie the optout to a specific message for reporting purposes. The message_hash can be obtained by using the %%mhash%% substitution tag in any message link. When the email is created and sent, the tag will be populated with the ID number of the actual message.	string	No	4lijfo409fajdj
status	Specifies whether to return error or success text. 0 – do not return text (default) 1 – return text	boolean	No	1
channel_source	Reserved for future use	string	No

Response

Field	Description	Example
status	A numeric code representing the result of the POST	1
message	A human-readable explanation of the numeric response code	User has been added

 

The different combinations of <status> and <message> are as follows:

status	message
1	User has been added
1	User has been sent a Double Opt-in Email
2	User has been updated
2	User had been sent a previous Double Opt-in Email and has not confirmed yet. They have been updated and been sent another Double Opt-in Email
3	User does not exist
3	This does not appear to be a valid email address
3	This subscriber has previously opted out&optout=1
3	Bad CID
3	This email address is on the suppression list
3	The external_id field must be less than 64 characters
3	Subscriber record could not be updated because it could not be uniquely identified.
3	The external_id could not be updated beause it already exists.
4	User has been removed
4	User was not added, they were previously unsubscribed

Response Codes

Response Code	Response Text	Description
200	User has been updated	Returned when method call is used to update an existing subscriber record.
200	User has been removed	Returned when method call is used to delete an existing subscriber record.
200	Subscriber opted out, but the message hash value provided is invalid, therefore could not be used to track optout against this message.	Returned when method call is used to delete an existing subscriber record, but the message hash is not valid.
201	User has been added	A new record has been successfully added to the subscriber database.
211	User added, but contact opt-in information not included because of malformed data	New record added to the subscriber database, but contact opt-in info could not be included (because of extra or unexpected characters).
212	User added, but profile information not included because of malformed data	New record added to the subscriber database, but contact profile info could not be included (because of extra or unexpected characters).
213	User added, but opt-in and profile information not included because of malformed data	New record added to the subscriber database, but contact opt-in and profile info could not be included (because of extra or unexpected characters).
214	User updated, but profile information not included because of malformed data	Existing subscriber database record has been updated, but profile info could not be included (because of extra or unexpected characters).
220	User had been sent a previous Double Opt-in Email and has not confirmed yet. They have been updated and been sent another Double Opt-in Email	Returned when a subscriber record is added or updated, and that record is still pending Double Opt-in Email confirmation.
404	User does not exist	The email address or the external ID provided in the request to update/unsubscribe/delete a contact record does not exist in the subscriber database.
420	Invalid Email Address
421	This subscriber has previously opted out&optout=1	Attempt to create a new contact record or update a record using an email address that has previously opted out.
423	This email address is on the suppression list	Attempt to create a new contact record or update a record using an email address that is listed in the global suppression list.
424	The external_id field must be less than 64 characters	The value provided in the <external_id> element exceeds the 64-character limit.
425	Subscriber record could not be updated because it could not be uniquely identified	Returned when the External ID feature is enabled for your account, and the request included an email address that appears multiple times in the subscriber database and there is no other information provided to uniquely identify the contact record.
426	The external_id could not be updated because it already exists	The value provided in the <new_external_id> element already exists.
427	User was not added, they were previously unsubscribed	An attempt to create a new subscriber record using an email address that has already been unsubscribed.
428	The new email provided already exists.	The email address provided in the element already belongs to another subscriber.
429	User was not added, firstname/lastname contains crlf.	New user could not be added to the database due to unexpected characters (either CRLF or LF) included in the First Name or Last Name fields.

Example Post

Example Response

Example Error

---