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.  It's the most efficient way to import 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.

cmd=smartsub&list_id=5&format=99&delimiter=|
email|first|last|custom_age
jane@domain.com|Jane|Doe|36
cmd=endsmartsub

The command is ‘smartsub’, the list to subscribe to is list_id ‘5’, the data is separated by pipe (|), the contact email address is ‘jane@domain.com’, 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]).

Example

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

cmd=smartsub&list_id=55&realm=myrealm_child&format=2&override_optout=1&prevent_update=1&delimiter=^
email^first^last^custom_gender
jane@domain.com^Jane^Doe^female john@domain.com^John^Doe^male
cmd=endsmartsub

Two new contacts, ‘jane@domain.com’ and ‘john@domain.com’, 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):

cmd=smartsub&list_id=55&realm=myrealm_child&override_optout=0&prevent_update=1&delimiter=^
email^first^last^custom_gender^format
jane@domain.com^Jane^Doe^female^2 john@domain.com^John^Doe^male^99
cmd=endsmartsub

Two new contacts, ‘jane@domain.com’ and ‘john@domain.com’, 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.

cmd=smartsub&list_id=55&realm=myrealm&override_optout=0&prevent_update=1&delimiter=^
customer_key^email^first^last^custom_gender^format
11293^jane@domain.com^Jane^Doe^female^2 14356^john@domain.com^John^Doe^male^99
cmd=endsmartsub

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:

cmd=smartsub&list_id=55&realm=myrealm&override_optout=0&prevent_update=1&delimiter=^
email^first^last^custom_gender^format^publishing_flight_id
jane@domain.com^Jane^Doe^female^2 14356^john@domain.com^John^Doe^male^99^25
cmd=endsmartsub

Errors

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.  

Arguments

The Smart Subscribe command supports the following arguments:

*Publishing Flight added in v16.16