API: HTTP Subscribe to List
The Subscribe command allows you to add a Contact to a list and update the Contact's data.
Arguments
The Subscribe command requires the following arguments: Command, Realm, Password, List, Format, and Data.
api_web?r=myrealm&p=mypass&c=sub&list_id=5&format=1&data=email,first^jane@domain.com,Jane
The command is ‘sub', the realm is ‘myrealm’ and the password is ‘mypass’. A plain text format subscription for 'jane@domain.com' will be added to list_id='5'.
The Subscribe command expects as least one field in the Data argument. The email address of the contact is always required to create a subscription record. If the contact does not yet exist, a Contact record will be created using the email address as the primary key. If the contact does exist, the Contact record will be updated with any data defined in the Data fields.
You can add one or many contacts with the same subscribe command. To add multiple contacts, include additional contacts separated by the carat (^) character. Each additional contact must have the same number of data fields defined.
The Subscribe command supports the following arguments:
Name | Req? | Description | Argument |
Command | Yes | Defines the command to use. | cmd=sub c=sub |
Realm | Yes | Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match. | realm=[realm_name] r=[realm_name] |
Password | Yes | Authentication code for API access. This is required, and the command will fail if the realm and password do not match. | pwd=[password] p=[password] |
List ID | Yes | Identifier of the list to apply the command. | list_id=[list_id] |
Format | Yes | The format of the email message content to send. Plain Text = 1 HTML = 2 Multipart MIME = 99 | format=[1,2,99]
|
Force Subscribe |
| When a Contact unsubscribes, in some instances an opt-out record is created preventing future subscriptions. To force a subscription, set Force Subscribe to 1. Records are not updated by default. | force_sub=[0,1]
DEFAULT==0 |
Override Subscription Confirmation Requirement |
| Lists include an option to require a contact to Confirm a subscription request through Subscription forms, Subscribe Links, and API calls. If this option is enabled, the API subscribe command will not add the subscription until after the contact clicks a link to confirm they wish to be added to the List. To ignore the requirement, set override_confirmation argument to 1. The subscription will be created and the confirmation email will not be sent to the contact. | override_confirmation= [0,1]
DEFAULT==0 |
Data | Yes | Contact related data. Email is always required, and additional fields are optional. | data=[fields] d=[fields] |
Examples
Using all commands and arguments (please note the command is wrapped for display purposes only):
api_web?r=myrealm&p=mypass&c=sub&list_id=5&format=99&force_sub=1&override_confirmation=1&data=email,first,last,custom_gender^jane@domain.com,Jane,Doe,female
The contact, ‘jane@domain.com’, will be subscribed to list ‘5’ in the realm ‘myrealm’ with the option to receive MIME messages. If the list requires subscription confirmation, the subscription will be created without the confirmation.
If a record for the contact already exists, then it will be updated. If it does not exist, a new record will be created with the first name, ‘Jane’, last name, ‘Doe’, and custom field “gender” set to ‘female’. Any optouts for the email address will be removed.
Duplicate Contact
To add a contact with the same email, but different first name and allow a duplicate instead of updating an existing contact, add the Duplicate flag to the DATA argument:
api_web?r=myrealm&p=mypass&c=sub&list_id=5&format=99&data=email,first,last,custom_gender,duplicate,format^jane@domain.com,JD,Doe,female,1,99
A contact with the same email address will be created with the first name, ‘JD’, last name, ‘Doe’, and custom field “gender” set to ‘female’.
Successful results return:
SUCCESS: Total Records Processed 1, Total Subscriptions 1, Records Added 1, Records Updated 0, Records Ignored (Optout Error)0, Records Failed Other Error 0
Multiple Contacts
To add multiple contacts in one command:
api_web?r=myrealm&p=mypass&c=sub&list_id=5&format=99&data=email,first,last,custom_gender,format^jane@domain.com,Jane,Doe,female,99^john@domain.com,John,Doe,male,99^joe@domain.com,Joe,Doe,male,99
In addition to the first record example above, a second and third record are created.
Successful results return:
SUCCESS: Total Records Processed 3, Total Subscriptions 3, Records Added 3, Records Updated 0, Records Ignored (Optout Error)0, Records Failed Other Error 0
Customer Key Example
Some systems have the ability to define a unique Customer Key per contact. If your realm has Customer Key enabled, then you must include the customer_key in the data argument along with email. For example:
api_web?r=myrealm&p=mypass&c=sub&list_id=5&format=99&force_sub=1&data=customer_key, email,first,last,custom_gender^11293,jane@domain.com,Jane,Doe,female
If the Customer Key is not included, the command will fail.
Publishing Flight Example
Some Realms have the ability to deploy campaigns to contacts in a specified order, called the Publishing Flight ID. If your realm has Publishing Flight enabled, then you can include the publishing_flight_id in the data argument along with email. For example:
api_web?r=myrealm&p=mypass&c=sub&list_id=5&format=99&force_sub=1&data= email,first,last,custom_gender,publishing_flight_id^jane@domain.com,Jane,Doe,female,25
Results
The Subscribe command outputs either a SUCCESS or FAILURE message.
SUCCESS
The Subscribe command success message returns the SUCCESS message and includes information about the records processed. The result format is:
SUCCESS: Total Records Processed [number_a], Total Subscriptions [number_b], Records Added [number_c], Records Updated [number_d], Records Ignored (Optout Error)[number_e], Records Failed Other Error [number_f]
The numbers reported in the results include the following:
Total Records Processed | Number of email addresses in the command |
Total Subscriptions | Number of subscriptions added or updated |
Records Added | Number of new Contacts |
Records Updated | Number of Contacts that already existed and updated |
Records Ignored Optout Error | Number of Contacts not subscribed because an optout was encountered. Can only be 0 if force_sub=1, or no optouts encountered. |
Records Failed Other Error | Number of contacts not subscribed because of some other error |
FAILURE
A Subscribe command will fail for several reasons, such as if an invalid list is specified or an optout is encountered. The result format is:
FAILURE: [Reason]