The Smart Relational Subscribe command, like the Subscribe and Smart Subscribe commands, allows you to add Contacts to a list and update Contact data. However, it is specialized for batches of contact 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 Large Batch 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 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 '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 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 realm supports Customer Key, the Customer Key is also required for each data row.
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, the Contact 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 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), each row will update that contact.
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 Contacts 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 contacts, ‘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 contact 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 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.
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 contact 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 contact, 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 |
Yes |
Name of the realm to run the command. |
realm=[realm_name] |
|
Header |
Yes |
API Password, or authentication code, for the realm. See Conventions for more information. |
password=[password] |
|
Header |
Yes |
When working with Relational Contacts batch process, the Is Relational Contact flag must be set. If set to 1, the import processor will complete import of the contacts in the file before processing any other Relational Bulk Imports. |
isrelationalsubscriber=1 |
|
Header |
|
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 contact'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 |
format=[1,2,99]
|
|
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 |
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 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, do not import contact |
override_optout=[0,1] DEFAULT==0 |
|
|
Data |
Yes |
Contact 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