Follow

Subscribe to List (Large Batch, pre Relational Data Import)

The Smart Relational Subscribe command, like the Subscribe and Smart Subscribe commands, allows you to add Subscribers to a list and update Subscriber data.  However, it is specialized for batches of subscribers that must be imported prior to importing related Relational Data.  This import method requires a specific  header flag along with the command to inform the system that all Relational Data imports must not process until the Smart Relational Subscribe import is complete. 

The Smart Relational Subscribe command uses a format similar to Smart Subscribe.  It requires a begin and end to define the subscription block, a flag in the header to indicate the type of import, and the following arguments in the data file body: Command, List, Delimiter, Header, Format Data, and Command End.

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

The command is ‘relationalsub’, 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 'relationalsub' command is a required header defining the fields to import.  The header uses the names of the Data Fields and custom field labeling convention.  

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 'endrelationalsub' command.

The Smart Relational 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 realm supports Customer Key, the Customer Key is also required for each data row.

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, the Subscriber record will be updated with any data defined in additional Data fields based on the Email + First Name, or Customer Key in supported realms. 

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), each row will update that subscriber.

Only include one 'relationalsub' command in each data file. To take advantage of Smart Relational Subscribe, upload your .dat and .sig files with the 'relationalsub' command first.  After the import has started, you can then upload any Relational Data import files.  The rest of the files will be picked up after the 'relationalsub' file has completed.  To check the status of the import, go to TASKS > CURRENT TASKS.  

Example

In order to identify the import as a Smart Relational Subscribe that must complete before other Relational Data imports can begin, the FTP API file Header must include the following argument: 'isrelationalsubscriber' set to true (1). In the examples below, the header indicates that the batch process is for Relational Subscribers that must be imported before related Relational Data.

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

realm=myrealm
password=mypass
isrelationalsubscriber=1
confirmation_email=jane.doe@mydomain.com
cmd=relationalsub&list_id=55&format=2&override_optout=0&prevent_update=0&delimiter=^

email^first^last^custom_newsletter
jane@domain.com^Jane^Doe^daily
john@domain.com^John^Doe^weekly
cmd=endrelationalsub

Two new subscribers, ‘jane@domain.com’ and ‘john@domain.com’, will be subscribed to the list with id ‘55’ in the realm ‘myrealm’, to receive messages in HTML format.  If a record for the subscriber already exists, then the record will be updated.  If the record does not exist, then a new record will be created with the first name, last name, and custom field “newsletter”.  If an opt out exists, then the subscription will NOT be created.

NOTE: The FTP API header argument 'confirmation_email' supports multiple comma separated email address to send a notification when the file has completed processing.  However, when using the 'relationalsub' command, the 'confirmation_email' header argument supports only a single email address.

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.

realm=myrealm
password=mypass
isrelationalsubscriber=1
confirmation_email=jane.doe@mydomain.com
cmd=relationalsub&list_id=55&override_optout=1&prevent_update=0&delimiter=:

customer_key:email:first:last:custom_newsletter:format
11293:jane@domain.com:Jane:Doe:daily:2 
cmd=endrelationalsub

Results 

Success

The Smart Relational Subscribe delivers an email to the Confirmation Email address defined in the Header.  The message is generated when the Data file is picked up and the process is complete.  The messages include the name of data file, name of the List imported into, number of subscriber rows processed, added or updated, and the number of errors.

Subscriber Import Complete
admin@mydomain.com
Mon 8/3/2020 7:58 AM
The import from relational_subscriber_import.dat has been completed and the subscribers have been associated with the list "Marketing Master"

Total records processed: 156
New subscribers added: 145
Subscribers updated: 10
Subscribers previously opted out: 0
------------------------------------
Errors (records not processed): 1

Email addresses that failed to import:
---------------------------------------
- Invalid email address: bad@nodomain

Errors

A Smart Relational Subscribe command will fail if an invalid list is specified, an opt out is encountered for the subscriber, or a format is not defined.  Failures result in an email message sent to the Confirmation Email defined in the header.  The message contains information related to the failure. 

If the import fails due to an invalid delimiter or missing 'isrelationalsubscriber' flag, the failure occurs before the import begins and you will only receive a notification email.  Other details about errors during the import are reported in the TASKS > TASK HISTORY page. 

Arguments

The Smart Relational Subscribe command supports the following arguments:

Name

Req?

Description

Argument

Header
Realm

 Yes

Name of the realm to run the command.  

realm=[realm_name]

Header
Password

 Yes

API Password, or authentication code, for the realm.  See Conventions for more information.

password=[password]

Header
Relational

 Yes

When working with Relational Subscribers batch process, the Is Relational Subscriber flag must be set. If set to 1, the import processor will complete import of the subscribers in the file before processing any other Relational Bulk Imports.

isrelationalsubscriber=1

Header
Confirmation Email

 

Specify who will receive a confirmation email after the data file is processed.  This message details the results of the process, such as any errors that occurred. Only a single address is supported for this command.

confirmation_email= [email_address]

Command

Yes

Defines the command to use.

cmd=relationalsub

cmd=endrelationalsub

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 Relational 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.  Supported delimiters include the same as supported in the Import wizard in the UI: tab, comma, pipe, caret, colon, semicolon ( \t , | ^ : ; )

delimiter=[single character or escaped tab]

Format

Yes

The subscriber's preferred format of the email message content to send.  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]

 

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,1]

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, do not import subscriber
1  = True, remove opt out and import subscriber

override_optout=[0,1]

DEFAULT==0

Data

Yes

Subscriber related data.  Email is always required, and additional fields are optional. Customer Key is also required in Customer Key enabled realms.

data=[fields]

* Added in v15.17

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

Comments

Powered by Zendesk