Follow

Subscribe to List (Large Batch)

The Smart Subscribe command, like the Subscribe command, allows you to add a Subscriber to a list and update the Subscriber's data.  However, it is meant for batches of 10,000 or more subscribers 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.  

NOTE: Because the SmartSubscribe is a batching command in itself, it should be the only command in the file on upload.  Do Not Include more than one SmartSubscribe command in the file.

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 subscriber 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 subscriber 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 subscriber 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 subscriber does not yet exist, a Subscriber record is created using the email address as the primary key.  If the subscriber does exist and updates are allowed, the Subscriber record will be updated with any data defined in additional Data fields. 

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

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 subscribers (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 subscribers, ‘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 subscriber 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 subscriber (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 subscribers, ‘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 subscriber 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 subscriber.  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_child&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

Errors

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

Arguments

The Smart Subscribe command supports the following arguments:

Name

Req?

Description

Argument

Command

Yes

Defines the command to use.

cmd=smartsub

cmd=endsmartsub

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.

list_id=[list_id]

Delimiter

Yes

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]

RECOMMENDED == | or ^

Prevent Update

 

To prevent existing subscriber 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

prevent_update=[0,false,1,true]

DEFAULT==0

Update Only

 

To update a subscriber 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.

do_not_subscribe=[0,false,1,true]

DEFAULT==0

Override Opt Out

 

The platform supports a sophisticated opt out protection system that makes it difficult to override the opt out wishes of subscribers.  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 subscriber, the opt out record will be removed and the subscription created.

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

override_optout=[0,false,1,true]

DEFAULT==0

Format

Yes

The subscriber'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 subscriber 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

format=[1,2,99]

 

Data

Yes

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

data=[fields]

 

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

Comments

Powered by Zendesk