Follow

Conventions

The FTP API method of communicating with the server is passive and asynchronous, where two processes run independently of one another.  A very specific protocol is used requiring two files.  The XML Data file contains commands that must be written in the proper XML format in order to be processed.  The Signal File is a blank file that indicates the XML Data File is ready to be processed.

Data File

The first file you must create and send is the XML data (.xml) file.  It is a file comprising a tranaction node with one or more command blocks.  The file contains the instructions to be processed, such as subscription commands.  The data file can be edited and viewed in a normal text editor or an XML editor.

In terms of naming conventions, you can use almost any file name as long as the extension is ".xml" to indicate it is a XML Data File.  It is best not to use spaces or special characters in the file name, as it may not function as expected on some systems.  Characters to avoid include:

%  *  ~  \  /  |  [space]

File names like ‘data0001.xml’, ‘test.xml’, and ‘subscription_data_oct_2002.xml’ are all valid.  However, in order to streamline troubleshooting should an error occur, we recommend using a combination of your realm name, the current date, and the type of commands in the file (if all of one type).  For example:

  • myrealm_201201_subscriptions.xml
  • myrealm_20120501_campaign.xml

XML Encoding

Use the standard xml encoding directive to specify the character set for your text data.  Use this when working with non-English characters.  For example, to specify utf-8 encoding:

<?xml version="1.0" encoding="utf-8"?>

You can use any of the standard, defined character sets.  By default, the importer assumes English with Western European encoding.

Transaction Block

The entire XML block must be encapsulated within a <transaction> tag.  This node contains tags identifying authentication information and options to control default behavior or perform tasks using the <command> tag.

In addition to the <command> tag, tags that may appear in the transaction block include:

Name

Description

Command

Realm

Authentication is based on realm and password.  The realm name is determined when your account is created and can be seen in the Welcome message you receive with your platform login credentials. 

The realm must be defined first. 

<realm>[realm_name]</realm>

Password

The password, also known as an authentication code, must be defined after the realm.  To generate the password, login to the platform and then go to CUSTOMER CENTER > API MANAGEMENT > SETUP API.

If you do not see a password in bold, red text, click Generate Password

Changing the code invalidates any files using the old code.  If the authentication code already exists and you regenerate it, make sure to notify everyone using any of the APIs.

<password>[password]</password>

Confirmation Email

You can 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.

To specify more than one email address, separate each using commas, semi-colons, or spaces.

This field must not exceed 255 characters (not including the confirmation_email= characters).

<confirmation_email> [email_address]</confirmation_email>

Opt Outs

Control the list level opt out behavior by modifying the opt out flag.  By default, an unsubscribe command removes a subscriber from a list and generates an opt out record.  This opt out record prevents the subscriber from re-subscribing to the specific list without a forced override.

To prevent the opt out record from being created, set the flag to false.

<optout>[0,false,1,true]</optout>

 

DEFAULT==true

Universal Opt Out*

To control opt out behavior on the broadcaster level, you must use a combination of the universal opt out flag and the list_id flag.  If set properly, when an unsubscribe command removes a subscriber from a list a Universal opt out record is also generated, removing the subscriber from all lists in every realm on the system.  This Universal opt out record prevents the subscriber from re-subscribing to any list in any realm. 

To generate a Universal opt out, set the flag to true, and then in the header, or in each Unsubscribe command, use list_id=0.

By default, this flag is set to false.

* NOTE: Universal Opt Out is only available on Broadcasters and must be enabled in the configuration file.  Please contact Support if you would like to use this command.

<universal> [0,false,1,true]</universal>

<list_id>0</list_id>

 

DEFAULT==false

Force Subscribe

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 Force Subscribe flag to true.  When an opt out record is found for a subscriber, the opt out record will be removed and the subscription created.

<force_subscribe> [0,false,1,true]</force_subscribe>

 

DEFAULT==false

Command Blocks

Within the transaction block of the Data File are one or more command blocks containing commands interpreted by the server daemon process.  All commands of a similar type (save, delete, subscribe, and unsubscribe) can be included in a single block, and each new command must appear in a new block.  Each Send and Launch command must appear in separate command blocks, one command per command block.  

If you have several hundred commands, you may wish to split commands of similar types into separate files, such as a file of Subscribe commands and a file of Launch commands.

The format for each command block follows XML standards.  Commands can take several arguments, depending on the type of command.  For example, to add a subscriber to a particular list, the command could be:

<command>   <type>subscribe</type>   <list_id>5</list_id>   <record>     <email>jane@domain.com</email>   </record> </command>

In this example, the command is ‘subscribe’, the list is ‘5’, and the address to subscribe is ‘jane@ domain.com’. In the following example, several subscribe commands are included in a single <command> tag with different data fields to import for each subscriber:

<command>   <type>subscribe</type>   <list_id>5</list_id>   <record>     <email>jane@domain.com</email>   </record>   <record>     <email>jon@domain.com</email>     <first>Jon</first>     <custom_age>35</custom_age>   </record>   <record>     <email>mary@domain.com</email>     <first>Mary</first>     <zip>98011</zip>   </record> </command>  

Record Blocks

Record blocks are contained within a command block and identify data for individual subscribers or email recipients.  For example, with a Subscribe command, the each record represents a Subscriber to import and subscribe to a list.

Each record uses tags to identify a subscriber, such as <email> and <first>.  In all cases, XML tags must be properly closed.  For example, the email address must be contained within the tags <email> and </email>.  The FTP API for XML Data parser is strict and expects well-formed, verbose XML.

The Subscriber Data fields include:  

<email>

<address_1>

<state>

<phone>

<first>

<address_2>

<zip>

<fax>

<last>

<city>

<country>

<company>

 

Two additional Subscriber Data fields are for special data:

<format>

To specify the format of the email messages your subscriber will receive, you can set the <format> in the Record block. 

plain_text or plain = plain text HTML = HTML multipart = Multi-part MIME

<customer_key>

Subscriber's unique identification string.  Only available on some systems.  This field is required when enabled in the realm settings.

Custom Fields

Custom fields can be specified by appending the string "custom_" to the field name.  For example, if your realm has a custom field named "age", specify it as a data field using "<custom_age>".  If you are attempting to import custom data and the data remains blank in the database, check that the custom field has been properly identified in the data file preceded by "custom_".  Please note that custom fields are case sensitive and long names or names with spaces are prone to error.

Item Blocks

If you are using a Send command to send one-off messages, and you have repeating data to incorporate into your messages, you must define one or more item blocks inside the <items> tag. 

Consider items as rows of data <row>, with each row containing one or more columns <column>.  The rows may contain information such as shipping details, search results, or other collection-like details to insert into your template content using a looping mechanism. 

Data in item blocks is not saved as Subscriber data in the database.  See the Send command for examples.    

Signal File

The second required file is a signal (.sig) file, an empty file to indicate that your data file is ready for processing.  As soon as it the signal file is detected, the processing daemon starts working on your data file.

The important part of a signal file is its name.  The contents of the file are not used, and the file should be empty.  The file name must exactly match the name of the data file, outside of the file extension.  If the signal file name is even slightly different, the data file will not be picked up to process.

After you have created and uploaded a data file, create a file with the same name and the extension ".sig" to indicate it is a signal file.  Upload the signal file to the server to indicate that your files are ready to be processed.

myrealm_date_import.xml    ----->     myrealm_date_import.sig  

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

Comments

Powered by Zendesk