Follow

Send One-Off Personalization using XML

Overview

The Send One-Off Message command allows you to send highly personalized content per Subscriber, such as:

  • shipment tracking
  • order confirmations
  • recurring saved search results  

Content for XML One-Off Message

One-off messages sent through the FTP API for XML are very flexible.  You can either send basic content by specifying a simple template, or you can use a combination of Articles and Logic statements in your template to create a unique, highly customized message for each Subscriber.  This robust model allows you to define various data and does not constrain the amount or type of information that can be contained within an article.  To customize the content per Subscriber, you must:

  1. Create an Article to call data from an XML file.
  2. Create a Template that calls the Article through a logical loop.
  3. Create an XML Data File with a Send command.
  4. In the Subscriber Record block, define an Item block with rows and columns of data to display in the message. 

As an example, the following message displays a simple shipping statement:

 --------------------------

Jane Doe,

Thank you for your recent purchase.  Please find a summary of your recent purchase below, along with shipment tracking information.

 

Item

Price

Shipping_number

Widget

$24.95

Z1 2345 128282

Sprocket

$19.95

Z1 2727 182883

Doohickey

$0.88

Z1 2345 189764


Thank you for shopping with us.

--------------------------- 

In this example, the Subscriber’s first and last names are taken from the Subscriber record in the database.  The shipping information is merged into the Template by the inclusion of several versions of an Article that grab information from the XML Data File. 

Article Example

The first step is to Create an Article and define the content.   Give the Article a name and enter the Body, then click SAVE.

You must know the names of the Item columns you will be defining in the XML Data File.  In this case, the column names are product, price, and shipping_number.  The HTML Body would appear as:

<tr>
   <td>%%$product%%</td>    
   <td>%%$price%%</td>    
   <td>%%$shipping_number%%</td>
</tr>

 

Since the resulting message will display each shipped item in a separate row, this Article is formatted using HTML, however plain text content is also an option.

Template Example

To merge XML defined items into a message, next Create a Template.  Define the Template Name, Subject and Body, then click SAVE.

The following is an HTML example, but Plain-Text can also be used:

<p>Dear %%$first%% %%$last%%: </p>
<p>Thank you for your recent purchase.  Please find a summary of your recent purchase below, along with shipment tracking information.</p>
<table>
   <tr>
      <td>Item</td>
      <td>Price</td>
      <td>Shipping_number</td>
   </tr>
%%foreach "shipped_items" article "shipping_rows"%%
</table>
<p>Thank you for shopping with us.</p>

The Subscriber Data tags %%$first%% and %%$last%% which call the Subscriber’s name.  The third tag in this example is a logic tag foreach:

%%foreach "shipped_items" article "shipping_rows"%%

The foreach tag is a logical looping mechanism to display rows of information through an article.  It checks the identified Item block and prints the corresponding article content for each row of defined data.  The loop does the following:

  1. Look at the XML Data File and find the Items block called “shipped_items” for this subscriber.
  2. If there is a <row> tag, then call the article “shipping_rows”.
  3. Print the article “shipping_rows” data for every <column> tag, matching it to a special tag defined in the article, such as %%$product%% which corresponds to the column named product.
  4. Continue until there are no new rows found.

XML Item Block

Information in an Item block follows a row/column data model.  Rows can contain any number of columns (as defined by your article template) and columns can contain any type of data.  Data specified within rows is not stored in the Subscriber record, and is only available through the XML Data File to create and send one-off email messages.

The Record block for the Subscriber includes at least one Item block identified by a name “shipped_items”, which is used in the Template to find the correct Item block.  Each column is also identified with a name so the Article can grab the correct content. 

In this example the rows of information are the products the Subscriber purchased.  Three rows defined the products purchased, and each row includes three columns of data: product name, price, and shipment tracking number.

<items name="shipped_items">
   <row>
      <column name="product">Widget</column>
      <column name="price">$24.95</column>
      <column name="shipping_number">Z1 234512 8282</column>
   </row>
   <row>
      <column name="product">Sprocket</column>
      <column name="price">$19.95</column>
      <column name="shipping_number">Z1 2727 182883</column>
   </row>
   <row>
      <column name="product">Doohickey</column>
      <column name="price">$0.88</column>
      <column name="shipping_number">Z1 2345 189764</column>
   </row>
</items>

If you want to define several rows of data for a column, you must use the CDATA identifier, <![CDATA[   ]]>.

XML Send Command Example

Using the sample above, following is a complete working file. This should be saved with a .xml extension, and be dropped in to the FTP site followed by an empty .sig (signal) file of the same name.

<transaction>
   <realm>myrealm</realm>
   <password>mypassword</password>
   <confirmation_email>me@mycompany.com</confirmation_email>
   <command>
      <campaign><name>Product Shipments</name></campaign>
      <type>send</type>
      <list_id>1234</list_id>
      <template_id>5678</template_id>
      <record>
         <email>jane@domain.com</email>
         <first>Jane</first>
         <last>Doe</last>
         <format>HTML</format>
         <items name="shipped_items">
            <row>
               <column name="product">Widget</column>
               <column name="price">$24.95</column>
               <column name="shipping_number">Z1 234512 8282</column>
            </row>
            <row>
               <column name="product">Sprocket</column>
               <column name="price">$19.95</column>
               <column name="shipping_number">Z1 2727 182883</column>
            </row>
            <row>
               <column name="product">Doohickey</column>
               <column name="price">$0.88</column>
               <column name="shipping_number">Z1 2345 189764</column>
            </row>
         </items>
      </record>
   </command>
</transaction>

Notes

URLs passed in this manner will not be changed to tracked links.  If you require link tracking in your message, those URLs should be included in the Template itself rather than passed through an XML data file.

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

Comments

Powered by Zendesk