Subscribe to List (Large Batch)

The Smart Subscribe command, like the Subscribe command, allows you to add a Contact to a list and update the Contact's data.  However, it is meant for batches of 10,000 or more contacts and is:

  • Faster: In a comparison of two identical data sets consisting of 67782 records with no custom data fields, normal subscribe completed in 36 minutes while  Smart Subscribe completed in 4 minutes.
  • Flexible: Data delimiter must be specified, and an optional parameter tells the system not to update existing data.
  • Smart: If the import has 50,000 or fewer records, high-speed mode is used, making use of advanced database commands to speed the import.  

The Smart Subscribe command uses a different format than most FTP API command.  Smart Subscribe requires a begin and end to define the subscription block.  It requires the following arguments: Command, List, Delimiter, Header, Format Data, and Command End.


The command is ‘smartsub’, the list to subscribe to is list_id ‘5’, the data is separated by pipe (|), the contact email address is ‘’, and the data is first name, ‘Jane’, last name, ‘Doe’, custom data field "age" is '36', and the subscription format is Multipart MIME (99).

The first line following the smartsub command is a required header defining the fields to import.  The header uses the names of the Data Fields and custom field labeling convention.  However you can also define the format per contact using format.

The lines following the header define the raw data to import.  Each line must include the same number of fields defined in the header.  If any lines are incomplete, the import will not process.  The raw data section ends with the endsmartsub command.

The Smart Subscribe command expects the email field in the Header and raw data, all other data fields are optional.  The email address of the contact is always required in order to create a subscription record.  During processing, email addresses are validated to ensure proper formatting. Data lines with invalid email addresses are ignored. 

If the contact does not yet exist, a Contact record is created using the email address as the primary key.  If the contact does exist and updates are allowed, the Contact record will be updated with any data defined in additional Data fields. 

Data lines containing duplicate contacts, where the email is the same and the first name is unique, result in unique contact records, or updates the unique contact records.  If there are two rows of data for the same contact (same email and first name), then the import will fail for that contact.

Smart Subscribe uses  a specific command to allow overriding opt outs, described below.  The override optouts should be used instead of the Force Subscribe command defined in the File header. 

To allow or prevent duplicate contacts (same email, unique first name), use the Allow Duplicates setting in the header portion of the file.  (allow_duplicates=[0,false,1,true]).


Using all commands and arguments (please note the command is wrapped for display purposes only):


Two new contacts, ‘’ and ‘’, will be subscribed to the list with id ‘55’ in the realm ‘myrealm_child’, a child of the Realm defined in the header, to receive messages in HTML format.  If a record for the contact already exists, then the record will not be updated.  If the record does not exist, then a new record will be created with the first name, last name, and custom field “gender”.  If an optout exists, then the subscription will be created and the optout removed. 

Using all commands and arguments with the format defined for each separate contact (please note the command is wrapped for display purposes only):


Two new contacts, ‘’ and ‘’, will be subscribed to the list with id ‘55’ in the realm ‘myrealm_child’, a child of the Realm defined in the header.  Jane is set to receive messages in HTML format, while John is set to receive messages in MIME format.  If a record for the contact already exists, then the record will not be updated.  If the record does not exist, then a new record will be created with the first name, last name, and custom field “gender”.  If an opt out exists, then the subscription will not be created and the opt out will remain. 

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.

11293^^Jane^Doe^female^2 14356^^John^Doe^male^99

Publishing Flight

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:

email^first^last^custom_gender^format^publishing_flight_id^Jane^Doe^female^2 14356^^John^Doe^male^99^25


A Smart Subscribe command will fail if an invalid list is specified, an opt out is encountered for the contact, or a format is not defined.  


The Smart Subscribe command supports the following arguments:







Defines the command to use.





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.


List ID


Identifier of the list to apply the command.




A single character field separator for raw data.  Smart Subscribe does not recognize quotation marks as data enclosures, and because commas are common characters within data, it is not recommended to use comma as a separator.

delimiter=[single character]


Prevent Update


To prevent existing contact data (e.g. first_name, last_name) from being overwritten, set to False.  If the data is all new, set to False to increase import performance. Records are updated by default.

0  = False, update records
1  = True, do not update records



Update Only


To update a contact record without creating a subscription, use the do_not_subscribe command.

0  = False, create subscription
1  = True, do not create subscription

List ID and Format are not required when the Update Only command is true.



Override Opt Out


The platform supports a sophisticated opt out protection system that makes it difficult to override the opt out wishes of contacts.  However, there are cases where you may want to override such requests.

By default, this flag is set to false.  To override opt out rules, you can force subscriptions by setting the Override Opt Out flag to true.  When an opt out record is found for a contact, the opt out record will be removed and the subscription created.

0  = False, do not remove opt out and import contact
1  = True, remove optout and import v





The contact's preferred format of the email message content to send.  If the format is not defined in the smartsub command, then it must be defined for each row of contact data.  Processing will stop if the format is not defined in the header or in the raw data.

1 = Plain Text
2 = HTML
99 = Multipart MIME





C ontact related data.  Email is always required, and additional fields are optional.


*Publishing Flight added in v16.16

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk