The Smart Unsubscribe command, like the Unsubscribe command, allows you to remove a Contact from a list. However, it is meant for batches of 10,000 or more contacts in order to improve performance. Smart Unsubscribe ignores all Contact data fields other than the email address to find matching contacts to remove from a list. Therefore, if you have multiple contacts with the same email address and different First Name (or Customer Key in supporting Realms), you may wish to use normal Unsubscribe instead.
NOTE: Because the Smart Unsubscribe is a batching command in itself, it MUST be the only command in the file on upload. Do Not Include other commands or more than one Smart Unsubscribe command in the file.
The Smart Unsubscribe command uses a different format than most FTP API command. It requires a begin to define the command block. It requires the following arguments: Command and List.
cmd=smartunsub&list_id=5
jane@domain.com
john@domain.com
The command is ‘smartunsub’, the list to subscribe to unsubscribe from is list_id ‘5’, the contact email addresses are ‘jane@domain.com’ and ‘john@domain.com.
The Smart Unsubscribe command expects only the email address of the contact in order to remove a subscription record. During processing, email addresses are validated to ensure proper formatting. Data lines with invalid email addresses are ignored. Any duplicate contacts that use the same email address will be removed from the list. Smart Unsubscribe does not support ignoring duplicates based on first name or Customer Key.
Example
Using all commands and arguments and header:
realm=myrealm
password=mypassword
confirm_email=myemail@mydomain.com
optout=1 // create an opt out in addition to removing the subscription
global=0 // do not remove all subscriptions from all lists
cmd=smartunsub&list_id=5
jane@domain.com
john@domain.com
Two contacts, ‘jane@domain.com’ and ‘john@domain.com’, will be removed from the list with id ‘5’ in the realm ‘myrealm’. In addition, an Opt Out will be recorded, which will prevent future subscriptions unless overridden.
Opt Out
An Opt Out record prevents a contact from being added back to a list without a specific override. By default, optout is not enabled and the subscription is simply removed. If optout=1, an opt out is created even if the contact email address is not subscribed to the specified list. If you do not wish to create an opt out, then set the header to optout=0. For more information about the Opt Out and Global Opt Out flags, see Conventions.
Customer Key
Some systems have the ability to define a unique Customer Key per contact. The Customer Key data field is not supported in Smart Unsubscribe. When submitting the Smart Unsubscribe command in a Customer Key Realm, only the email address is used to find contacts. If multiple contacts have the same email address and different Customer Keys, every contact with the email address will be removed, regardless of Customer Key.
Errors
A Smart Unsubscribe command will fail if an invalid list is specified or a contact does not exist.
Arguments
The Smart Unsubscribe command supports the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=smartunsub |
|
List ID |
Yes |
Identifier of the list to apply the command. List is required, but may be set to 0 if Global Opt Outs or Opt Outs are allowed in the Header of the data file. See Conventions for more details. |
list_id=[list_id] |
* Feature added in v12.07.0