legacy.manage_subscriber

‹ BACK TO API PAGE


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@bluehornet.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/​ems/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.

Example Post

<methodCall>

<methodName>legacy.manage_subscriber</methodName>

<email>new_guy@bluehornet.com</email>

<status>1</status>

<firstname>Bill</firstname>

<city>San Diego</city>

<postal_code>92127</postal_code>

<custval1234>Fido</custval1234>

<subscriber_ip>256.256.256.256</subscriber_ip>

<grp>1234</grp>

</methodCall>

Example Response

Example of a successful method call:

<methodResponse>

<item>

<methodName>legacy.manage_subscriber</methodName>

<responseData>

<status>2</status>

<message>User has been updated</message>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>

Example Error

Example of an unsuccessful method call

<methodResponse>

<item>

<methodName>legacy.manage_subscriber</methodName>

<responseData>

<status>3</status>

<message>User does not exist</message>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>


Back to API Reference Guide