The Subscribe command requires the following arguments: Command, List, and Data.
cmd=sub&list_id=5&data=email,first^jane@domain.com,Jane
The command is ‘sub', and a 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.
Example
Using all commands and arguments (please note the command is wrapped for display purposes only):
cmd=sub&realm=myrealm_child&list_id=55&format=99&data=email,first,last,custom_gender ^*jane@domain.com,Jane,Doe,female
OR
cmd=sub&realm=myrealm_child&list_id=55&data=email,first,last,custom_gender,format_text^jane@domain.com,Jane,Doe,female,1,mime
Both above commands perform the same task. The contact, ‘jane@domain.com’, will be subscribed to list ‘55’ in the realm ‘myrealm_child’, a child of the realm defined in the header, with the option to receive MIME messages.
If a record for the contact already exists, then it will not 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 will be removed.
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:
cmd=sub&realm=myrealm&list_id=55&format=99&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:
cmd=sub&realm=myrealm&list_id=55&format=99&data=email,first,last,custom_gender,publishing_flight_id^jane@domain.com,Jane,Doe,female,25
Errors
A Subscribe command will fail if an invalid list is specified or if an optout is encountered for the contact.
Arguments
The Subscribe command supports the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=sub |
|
Realm |
|
Name of the realm to run the command. This is optional and only necessary when submitting files to a parent realm to manipulate data for a child realm. |
realm=[realm_name] |
|
List ID |
Yes |
Identifier of the list to apply the command. If you are using one file to perform the same command for several lists, group the command lines in your file by Command and List. This will improve processing efficiency. Alternately, define the list in the header instead of per command. |
list_id=[list_id] |
| Format |
The contact's preferred format of the email message content to send. Plain Text = 1 HTML = 2 Multipart MIME = 99 |
format=[1,2,99]
DEFAULT==1
|
|
| Data | Yes | Contact related data. Email is always required, and additional fields are optional. |
data=[fields] |
*Publishing Flight added in v16.16