The Unsubscribe command allows you to remove one or more contacts in a small batch from a single list. The command requires the following arguments: Command, List, and Data.
cmd=unsub&list_id=5&data=email^john.smith@domain.com
The command is ‘unsub', and the contact with email 'john.smith@domain.com' will be unsubscribed from list_id '5'. No other changes will be made to the Contact record.
The Unsubscribe command expects as least one field in the Data argument. The email address of the contact is always required to remove a subscription record.
You can remove one or multiple subscriptions with the same Unsubscribe command. To remove multiple subscriptions, include additional contacts separated by the carat (^) character. Each additional contact must have the same number of data fields defined.
In addition to the ability to unsubscribe from a single list, you can set the list_id to ‘0’ and the global flag to true (1) to generate a Global Opt Out. This removes the specified contact from all lists in the realm. It also generates a Global Opt Out record so the Contact will not be added to any lists in the future without a forced override.
Example
Using all commands and arguments (please note additional email addresses should be on a new line):
cmd=unsub&realm=myrealm_child&list_id=55&data=email,first^jane@domain.com,Jayne
^jane@domain.com,JD
^john@domain.com,John
Three contacts will be removed from the list_id '55' in the realm 'myrealm_child', a child of the realm defined in the header.
Global Opt Out
cmd=unsub&realm=myrealm_child&list_id=0&data=email,first ^jane@domain.com,Jayne
The contact will be removed from every list for which a subscription exists in the 'myrealm_child' realm, and a global opt out record will be created.
Customer Key
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. If the Customer Key is not included, the command will fail.
cmd=unsub&realm=myrealm_child&list_id=55&data=customer_key,email ^11293,jane@domain.com
Errors
An Unsubscribe command will fail if a contact record for the defined email address does not exist, if the list does not exist, or if a subscription does not exist for the list.
Unsubscribe will also fail if more than one contact is found with the same email address. Since Contact records are allowed to have the same Email address as long as the First Name is unique, you may wish to include the first name in your Unsubscribe command to avoid encountering errors or removing the wrong Subscription.
Arguments
The Unsubscribe command supports the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=unsub |
|
Realm |
Name of the realm to run the command. This is optional, and only necessary when submitting a file 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. |
list_id=[list_id] |
| Data | Yes | Contact related data. Email is always required, and additional fields are optional. |
data=[fields] d=[fields] |