XML Submit Document

XML Submit Document

An XML Submit Document is sent to the Transact server by the user’s system, which instructs the Transact server to send an email in response to a transaction on the user’s system.

Overview

This section discusses topics that are related to the XML Submit document.

Within this article, you can find:

  • XML Submit Document Template
  • Example of an XML Submit document
  • Methods for Sending Content by using the XML Submit document
  • XML Format
  • Content and Formatting

You can also find information on:

XML Submit Document Template

<XTMAILING>
<RECIPIENT>
<EMAIL>demo@email.com</EMAIL>
<BODY_TYPE>HTML</BODY_TYPE>
<PERSONALIZATION>
<TAG_NAME>World_Air_Confirmation_Body</TAG_NAME>
<VALUE><![CDATA[This is the <b>body</b> of the email.]]></VALUE>
</PERSONALIZATION>
</RECIPIENT>
</XTMAILING>

Example of an XML Submit Document

The code that is illustrated below is a brief example of what is typically generated by the user’s backend system and is given for reference only. Transact uses standard XML syntax and the schema that is defined in Transact XML Submit Schema and the XML API section of the documentation. Data must be provided in this exact format.

Note: A typical submission would not necessarily include all elements.
example_of_xml_submit_doc.png

Methods for Sending Content by using the XML Submit Document

There are two methods for assembling a transactional email in Transact:

  1. Limit the Mailing template to serving as a simple placeholder for personalization tags, while the rest of the content for the mailing is contained within the XML Submit document.
  2. Provide most of the HTML formatting in the mailing template along with personalization tags that are interspersed in the formatting of the template. At mail generation time, only the values for the various personalization tags are merged into the template from the XML submission envelope.

See the Example Mailings article in this topic. It provides detailed examples of the two methods for assembling a transactional email in Transact.

XML Format

The user’s system must specify the following information in the proper XML format:

  • Campaign (Group) ID
  • Contact email address
  • Personalized content by Template tag name and value

Notes:

  • The XML formatting must be exact. XML tags and tags in can
    be in lower, upper, or mixed case, but tags must exactly. Booleans (true, false) must be in lowercase.
  • A Template and corresponding campaign must be set up in .
  • If the user’s system can’t generate an XML document in the proper XML format, Professional Services can convert the file. Contact Client Support for more information.

The user’s system can specify the following information, in the proper XML format:

  • Error response instructions, if other than default
  • Batch or individual processing instruction
  • Save column instructions
  • Transaction ID
  • Updates to contact records
  • Hyperlinks to track, with personalization

See a class=”xref” href=”#deki_39220″ title=”This article contains details about General Submit Elements and Recipient and Content Elements.”>XML Submit Element Definitions for information on how to use these XML elements.

Notes:

  • The Transact server returns a Response Document. See the XML Response Document section in this document for more information.
  • Support must activate Transact on a user’s account.

Content and Formatting

You can include content through several mechanisms, all of which use the Template field tags and the XML TAG_NAME / VALUE element. These include:

  • Passing content through an XML TAG_NAME / VALUE element (corresponding to a template field tag).
  • Using content that is hosted in the template by using a blank XML TAG_NAME / VALUE
    element.
  • Passing content through a CDATA element nested in a TAG_NAME / VALUE element.
  • Including a hyperlink to content on another server through one of the above methods.

Notes:

  • XML Tags are alphanumeric fields. Punctuation and the following ‘Reserve’ characters are not allowed in the XML tags unless placed in a CDATA section (for example, ! * ‘ ( ) ; : @ & = + $ , / ? % # [ ]) . The underscore character “_” is an exception.
  • You can only use an XML CDATA section within a TAG_NAME / VALUE element.
  • You cannot nest a Transact XML tag within the CDATA section.
  • You can include hyperlinks in a template or XML and use
    tracking with either.
  • You can use Dynamic Content if you implemented it on your backend system.
  • Each tag (field) has a 4000-character limit, including white spaces.
Note: Older databases might have a 255-character limit. Check with Client Support for more information or if the older database limit is an issue.

HTML

You can use text, XML, XSL, XHTML, HTML, and hyperlinks within a CDATA section or the template. See the example code in the XML Submit document below.

Notes:

  • No processing of any code (logic or transformation) placed in text or CDATA content is done on the Transact server, including within Template tags.
  • You can track hyperlinks in CDATA and XML text.

CSS Stylesheets

Transact supports CSS Style formatting within a CDATA element tag, which remains unparsed. The styles can be in the following formats:

  • Inline styles
  • Internal stylesheet
  • Externally linked stylesheet.

See the example code in the XML Submit Document section above.

Engage can track hyperlinks that are submitted in the XML and XML CDATA (you can also
include personalization). For more information on creating hyperlinks, see the Hyperlink Tracking and Personalization section in this document.

  • XSL-style formatting, except as used in CDATA.
  • Dynamic Content Rulesets from (however, Transact can reference dynamic content on the user’s server).
  • Inbox Monitoring
  • Share-to-Social

Contact
Client Support for Professional Services on this and other web Service
support.

Example of a Transact mailing

Use the code examples in the topic as a reference for your own Transact
mailings.

Overview

This article includes the following examples of a Transact mailing submission:

  1. Mailing Template with content and personalization fields
  2. XML Submission Document
    1. Use with content in mailing template.
    2. Use with an empty mailing template and content in HTML CDATA

Content in Template

The following example illustrates a complex application that uses a mailing template with content plus a number of fields that insert content that is passed from the XML document.

Figure 1. Mailing Template

XML Submission Document: Use with content in mailing template

Below is the sample XML Submission Document containing only the data for the personalization tags used for generating the mailing from the template.

Note: Notice that there is a PERSONALIZATION element with a
TAG_NAME/VALUE pair for each of the personalization tags in the mailing template. In the sample above, the values for the personalization tags are all text. In a real-world example, these personalization TAG_NAME values can also contain HTML encapsulated in CDATA.
<XTMAILING>
<CAMPAIGN_ID>300402</CAMPAIGN_ID>
<TRANSACTION_ID>TRANS-1236</TRANSACTION_ID>
<SHOW_ALL_SEND_DETAILS>true</SHOW_ALL_SEND_DETAILS>
<SEND_AS_BATCH>false</SEND_AS_BATCH>
<NO_RETRY_ON_FAILURE>false</NO_RETRY_ON_FAILURE>
<RECIPIENT>
<EMAIL>demo@email.com</EMAIL>
<BODY_TYPE>HTML</BODY_TYPE>
<PERSONALIZATION>
<TAG_NAME>PASSENGER</TAG_NAME>
<VALUE>Some info</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>RECORD_LOCATOR</TAG_NAME>
<VALUE>Body</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>TICKET_TYPE</TAG_NAME>
<VALUE>Body</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>TICKET_NUMBER</TAG_NAME>
<VALUE>0061296848484</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_TRAVEL_DATE</TAG_NAME>
<VALUE>Body</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_FLIGHT_NUMBER</TAG_NAME>
<VALUE>#545</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_DEPARTURE_TIME</TAG_NAME>
<VALUE> February 21, 10:00 AM EST (morning) </VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_TRIP_TITLE</TAG_NAME>
<VALUE>Atlanta Hartsfield-Jackson ATL (ATL)
to Salt Lake City International (SLC)</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_DEPARTURE_AIRCODE</TAG_NAME>
<VALUE>ATL</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_CLASS</TAG_NAME>
<VALUE>Economy</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_ARRIVAL_TIME</TAG_NAME>
<VALUE> February 21, 12:12 PM MST (afternoon) </VALUE> 
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_ARRIVAL_AIRCODE</TAG_NAME>
<VALUE>SLC</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_SEAT_ASSIGNMENT</TAG_NAME>
<VALUE>46B</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_TRAVEL_DATE</TAG_NAME>
<VALUE>Body</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_FLIGHT_NUMBER</TAG_NAME>
<VALUE>#3913</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_TRIP_TITLE</TAG_NAME>
<VALUE>Salt Lake City International (SLC)
to Boise Air Term. (Gowen Fld) (BOI)</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_DEPARTURE_TIME</TAG_NAME>
<VALUE> February 21, 3:10 PM MST (afternoon) </VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_DEPARTURE_AIRCODE</TAG_NAME>
<VALUE>SLC</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_CLASS</TAG_NAME>
<VALUE>Economy</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_ARRIVAL_TIME</TAG_NAME>
<VALUE> February 21, 4:16 PM MST (afternoon) </VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_ARRIVAL_AIRCODE</TAG_NAME>
<VALUE>BOI</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_SEAT_ASSIGNMENT</TAG_NAME>
<VALUE>7D</VALUE>
</PERSONALIZATION>
</RECIPIENT>
</XTMAILING>

XML Submission Document: For empty mailing template

Below is the sample XML submission document that uses an empty mailing template that contains only one personalization field: %%WorldAir_Confirmation_Body%%

We provide the content in the example formatted in HTML (within a CDATA section) and also use a stylesheet in the HTML.

<XTMAILING>
<CAMPAIGN_ID>300401</CAMPAIGN_ID>
<TRANSACTION_ID>TRANS-1234</TRANSACTION_ID>
<SHOW_ALL_SEND_DETAIL>true</SHOW_ALL_SEND_DETAIL>
<NO_RETRY_ON_FAILURE >false</NO_RETRY_ON_FAILURE>
<RECIPIENT>
 <EMAIL>demo@email.com</EMAIL>
 <BODY_TYPE>HTML</BODY_TYPE>
 <PERSONALIZATION>
 <TAG_NAME>WORLD_AIR_CONFIRMATION_BODY</TAG_NAME> 
 <VALUE>
<!--CDATA section with HTML content and style sheet -->
<![CDATA[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtm...ansitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv='Content-Type' content='text/html; charset=iso-8859-1' />
<title>Untitled Document</title>
<style type='text/css'>
<!--
.style1 {
font-family: Arial, Helvetica, sans-serif;
font-weight: bold;
font-size: 14px;
}
.style2 {
font-family: Arial, Helvetica, sans-serif;
font-weight: bold;
font-size: 24px;
}
.style4 {
font-family: Arial, Helvetica, sans-serif;
font-size: 14px;
}
.style5 {
font-family: Arial, Helvetica, sans-serif;
font-size: 10px;
}
-->
</style>
</head>
<body>
<img name="Cont_0" src="http://demo.worldair.com/world_air_banner.JPG">
<p><span class='style1'>Thank you for booking your 
travel with World Air! Below is your confirmation of travel and your </span><br />
 <span class='style1'>itinerary. Have a safe trip! </span><br />
<p><strong>Passenger(s):</strong> BILL JONES <br />
 <strong>World Air Lines record locator</strong>: PCCUOF<br />
 <strong>Ticket type requested:</strong> electronic (e-ticket) <br />
 <br />
 <!-- fi -->
 <strong>Orbitz record locator</strong>: 5I84Z8K5<br />
 <strong>Airline ticket number(s)</strong>: 0061296848482<br />
 <br />
 <!-- lipt -->
 <strong>Tuesday, February 21, 2006</strong><br />
 World Air Lines # 545<br />
 <br />
 Atlanta Hartsfield-Jackson ATL (ATL) to Salt Lake City International (SLC)<br />
 <strong>Departure (ATL):</strong> February 21, 10:00 AM EST (morning)<br />
<strong>Arrival (SLC):</strong> February 21, 12:12 PM MST (afternoon)<br />
<br />
 <strong>Class:</strong> Economy<br />
<!-- seatmap -->
<strong>Seat assignment:</strong> 46B <a 
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=1" 
href="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=1"><br 
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=1" />
 view/change seats</a><br />
 <!-- end carrierSupported = true -->
 <!-- end hasStarted = false -->
 <!-- end hasSeatAssignments = true -->
 <br />
 <!-- lipt -->
 <strong>Tuesday, February 21, 2006</strong><br />
 World Air Lines # 3913<br />
 Operated by: SKYWEST AIRLINES - Please check in with the operating carrier<br />
 <br />
 Salt Lake City International (SLC) to Boise Air Term. (Gowen Fld) (BOI)<br />
 <strong>Departure (SLC):</strong> February 21, 3:10 PM MST (afternoon)<br />
 <strong>Arrival (BOI):</strong> February 21, 4:16 PM MST (afternoon)<br />
 <br />
 <strong>Class:</strong> Economy<br />
 <!-- seatmap -->
<strong>Seat assignment:</strong> 7D <a 
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=2"
 href="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=2"><br 
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=2" />
view/change seats</a><br />
<!-- end carrierSupported = true -->
<!-- end hasStarted = false -->
<!-- end hasSeatAssignments = true -->
<br />--------------------------------<br /><br />
<!-- lipt -->
<strong>Thursday, February 23, 2006</strong><br />
World Air Lines # 488<br /><br />
Boise Air Term. (Gowen Fld) (BOI) to Salt Lake City International (SLC)<br />
<strong>Departure (BOI):</strong> February 23, 8:00 AM MST (morning)<br />
<strong>Arrival (SLC):</strong> February 23, 9:05 AM MST (morning)<br />
<strong><br />
Class:</strong> Economy<br />
<!-- seatmap -->
<!-- has no seat assignment -->
<strong>Seat assignment:</strong> <a 
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=3"
href="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=3"><strong 
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=3">
choose seats</strong></a><br /><br />
<!-- lipt -->
<strong>Thursday, February 23, 2006</strong><br />
World Air Lines # 646<br /><br />
Salt Lake City International (SLC) to Atlanta Hartsfield-Jackson ATL (ATL) <br />
<strong>Departure (SLC):</strong> February 23, 10:10 AM MST (morning)<br />
<strong>Arrival (ATL):</strong> February 23, 3:50 PM EST (afternoon)<br /><br />
<strong>Class:</strong> Economy<br />
<!-- seatmap -->
<strong>Seat assignment:</strong> 42E <a 
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=4"
 href="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=4"><br
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=4" />
view/change seats</a><br />
<!-- end carrierSupported = true -->
<!-- end hasStarted = false -->
<!-- end hasSeatAssignments = true --></p>
<p>If you would like to change your mailing settings, 
click <u>here</u> to edit your web profile.</p>
<p><a xt="SPCLICK" name="www_spopdemo_com" 
href="http://www.spopdemo.com">click here for spop</a></p>
</body>
</html>
]]> <!--End CDATA section -->
</VALUE>
 </PERSONALIZATION>
 </RECIPIENT>
 </XTMAILING>

Hyperlink Tracking and Personalization – Dynamic Link Leader (DLL)

Transact can track hyperlinks that are submitted in the XML CDATA that uses Dynamic Link Leader (DLL) URL encoding.

When you are submitting encoded links in the XML document,
tracks clicked URLs and the resulting data is available in the Reporting section.

Notes:

  • You can use personalization within the URL, but you must include the personalization field and value in the XML submission. This allows to make the correct substitutions from the database when a contact clicks the encoded URL.
  • This section is only for links that are submitted in the XML file. automatically tracks all links that are created within the Mailing Template (with no additional development work required).

Host Server URLS

Pod Host Server URL
1

sdm3.rm04.net

2

recp.rm02.net

3

recp.mkt32.net

4

recp.mkt41.net

5

recp.mkt51.net

6

recp.mkt61.net

or

links.mkt61.net

7

recp.mkt71.net

Configure an XML Submission with Tracked Links

To configure an XML Submission with tracked links:

  1. Convert the URLs in the submission to DLL-encoded links.
  2. If URLs contain personalization, add elements for each field to the SAVE_COLUMNS section and to the PERSONALIZATION section with the correct value for the contact.
  3. Make sure that the contact database in contains the fields corresponding to the personalization elements defined in the XML submission (for example, custom fields).
  4. Perform a test send, click links in the received mailing, and make sure that the redirected URL contains the correct link and personalization substitutions.
  5. Check reporting after you allow enough time for the tracking to occur and display in .

Notes:

  • If you have a custom domain available, use it. For example, links.customdomain.com
  • For personalization values to appear in the mailing, you must include the value in the Mailing Body of the Mailing Template.
  • To save the personalization values in the database, you must create the fields in your database and use the SAVE_COLUMN element for that XML tag.
  • Dynamically generated links that are on the sending system are included in the XML that uses the CDATA tag, in the Personalization section, within a CDATA section.

Dynamic Link Leader (DLL) Encoding

You can include links (dynamically generated on the sending system) in the XML by using a CDATA section in the Personalization element. can then track these hyperlinks for clicks. In addition, you can include personalized information, such as account numbers, within the hyperlink and save as query string values.

You need to identify trackable links for by preceding them with a Link Name, as shown in the example below:

XML Example

<PERSONALIZATION>
 <TAG_NAME>XX</TAG_NAME>
 <VALUE>
 <![CDATA[ Insert link and other information 
 in place of this text ]]>
 </VALUE>
Format: <![CDATA[Here is a link: 
 <[link name and type]a href="">Click here</a> ]]>

Composing a link

The following illustrates how to compose various links for the transaction email. In the
sample transaction email below, the following hyperlinks are illustrated:

  • A hyperlink to the sponsor’s website with tracking but no personalization.
  • A hyperlink to a lodging website with tracking.
  • A hyperlink to a special offer website with an offer number and with tracking.
sample_transaction_response_email.png

See the examples below for the preferred composition of links A, B, and C in the XML Submit section.

Link A: Hyperlink to the sponsor’s Web site included in the
mailing body

Example 1 – Contact View (Email Message)

contact_view_email_message.png

Example 2 – Mailing Template

ex2_mailing_template.png

XML Personalization

You do not need a Personalization element for this example. will automatically track all hyperlinks included in the mailing body. You can also place text and hyperlinks in the XML (see Link B example below).

Link B: Hyperlink to a lodging Web site (with tracking)

Create a hyperlink to substitute using a field (HotelBrand_Link) in the template text:

Example 1 – Contact View (Email Message)

linkb-contact_view_email_msg.png
Note: In the example email text, you would need to use another XML tag and Template field (both not shown) to change the “SleepBetter” brand name to correspond with the hyperlink.

Example 2 – Mailing Template

linkb-mailing_template.png

Example 3 – XML

<PERSONALIZATION>
 <TAG_NAME>HotelBrand_Link</TAG_NAME>
<VALUE><![CDATA[ 
 <a href="http://recp.mkt32.net/ctt?m=%%MAILIN...leepbetter.com">Click here</a> ]]>
 </VALUE>
</PERSONALIZATION>

Example 4 – URL with Query String

The first part of the string is a constant and must be included for tracking:

<a href=”http://recp.mkt32.net/ctt?m=%%MAILING_ID%%&r=%%RECIPIENT_ID%%&b=0&j=%%JOB_ID_CODE%%

Notes:

  • Do not insert information in place of the %%X%% placeholders.
  • If you have a custom domain available, use it. For example, links.customdomain.com
  • You must create a field for the link in (such as HotelBrand_Link) in both the database and the Mailing Template. You can also place the text in the Template (if the link will always be there), or dynamically place it in the XML CDATA section with the hyperlink.
  • The value for the tag (HotelBrand_Link) can accommodate all text, including HTML and styles.

Example:

<VALUE><![CDATA[<p><b><style “color:#FF0000”>Thank you for booking with</style>
<a href="http://www.abc-travel.com">ABC-Travel.com</a>]]>

Notes:

  • This example does not show tracking information.
  • All information that is placed in the XML must appear within the Personalization element for each contact (if used). For example, if there are 10 contacts, you can enter the information 10
    times.
  • It is not necessary to use the SAVE_COLUMNS element for this hyperlink and text unless you want to save the values to the database for future reference.

The remainder of the Query string includes the actual hyperlink and personalization:

&k=Lodging_Link&kx=1&kt=12&kd=http://www.sleepbetter.com
Parameter: Name and Value Description

&k=Lodging_Link

Name of the link. This name is the tracking tag and identifies the link in clickthrough reports.

&kt=12

Specify the type of hyperlink.

1 Regular

12 Personalized

5 Clickstream

&kd=http://www.sleepbetter.com

The destination hyperlink [do not include quotation marks (“) around the hyperlink].

&kx=1

Link cross-reference. Specify whether to use the KD you entered above (or to default to the
database).

0 Ignore KD link above and default to database (not preferred).

1 Ignore database and use destination specified in KD above (typical).

See
Query String Parameters for more information on parameter names and values.

If you plan to have all text that is dynamically placed in the XML CDATA section, the CDATA section with the tracking hyperlink should appear as follows:

<PERSONALIZATION>
  <TAG_NAME>HotelBrand_Link</TAG_NAME>
<VALUE><![CDATA[Have you made lodging arrangements? %%Brand%%      
   <a href="http://silverpop.com/ctt?m=%%MAILING...leepbetter.com">Web site</a>.
]]>
</VALUE>
</PERSONALIZATION>

Link C: Hyperlink to a Web site using with a personalized offer number and tracking

Personalizing links with unique data, such as unique special offer codes and account
numbers requires the use of a query string, and possibly additional personalization tags with
corresponding values and tag substitutions. By embedding the URL query string for the destination
website with parameters, you can insert special offer codes automatically in forms at the site, and
tracking can be done on the website to determine the effectiveness of advertising and clickthroughs.
parameters appear in the query string for easy correlation with information.

You can insert data-embedded query strings as a complete string or you can use personalization tags to complete the string. See the example below to view how to use personalization tags to construct the message and complete the query string.

Note: The following message and code is an example of a standardized entertainment promotional message and hyperlink that you can place in each Transaction Response email. It is customizable so you can insert different sponsor names into the message with different URLs and different promotional codes that appear in the message and the query string. can track clickthroughs showing how many clicks each sponsor received.

This example shows the brand name, tracked hyperlink, and promotional code to substitute
that uses fields and XML tags (Brand, code, Promo1 with query string code) in the Template text.

Example 1 – Contact View (Email Message)

linkc-contact_view.png

Example 2 – Mailing Template

linkc-mailing_template.png

Example 3 – XML

linkc-example3_xml.png

Example 4 – Parameters and Query String

The following table provides the parameters and query string used in the preceding code:

&k=PromoSB&kx=1&kt=5&kd=http://www.starchasers.com%3FCode%3D%25%25Code%25%25

Parameter: Name and Value Description
&k=PromoSB

Link Name parameter and name. This is the tracking tag and you must give a different name for each hyperlink. You can view this information in the Clickthroughs area of the Reporting section.

Note: If you do not change this name, forwards the clickthrough to the hyperlink associated with the name, not the newly embedded hyperlink.
&kt=5

Specify the type of hyperlink:

5Clickstream (personalized and tracked)

&kd=http://www.starchasers.com%3FCode%3D%25%25Code%25%25

Hyperlink (illustrated in the query string with a Personalization tag). Do not include quotation marks (‘) around the hyperlink.

Important: Use the UTF-8 character hexadecimal equivalents for
non-alphanumeric characters.
kx=1

Link cross-reference. Specify whether to use the KD you entered above (or to default to the database).

0 – Ignore KD link above and default to database (not preferred).

1 – Ignore database and use destination that is specified in KD above (typical).

Notes:

  • automatically places the Brand and Code values in the
    message, and in the hyperlink query string. (Brand and Code are tags and values that are placed by you in the XML Personalization section.)
  • You must add the personalization fields to the database (Brand, Code, and Promo1 in the example above). Do not add an XML tag for the ‘&k’ parameter.
  • You must use the SAVE_COLUMN element to ensure the personalized hyperlinks work for your contacts.
  • The parameters (MailingID, UserID, JobID, and ReportId) appears in the query string at the destination website. Other parameters, such as CAMPAIGNID and email address, do not appear unless you include them as XML personalization (both tag and value) and query string parameters.

What to Expect – String Appearance

In the ‘Link C’ example above, you can expect to see different strings at different phases in the communication process. The submitted XML, the email hyperlink, and the browser redirect all have different characteristics. In the example, you would see the following:

Example 1 – XML

<PERSONALIZATION>
       <TAG_NAME>Brand</TAG_NAME>
           <VALUE>StarChasers</VALUE>
    </PERSONALIZATION>
    <PERSONALIZATION>
       <TAG_NAME>Code</TAG_NAME>
          <VALUE>441605</VALUE>
    </PERSONALIZATION>
    <PERSONALIZATION>
       <TAG_NAME>Promo1</TAG_NAME>
           <VALUE><![CDATA[      
   <a href="http://recp.mkt32.net/ctt?m=%%MAILIN...PIENT_ID%%&b=0
 &j=%%JOB_ID_CODE%%&k=PromoSJ&kx=1&kt=5&kd=http://www.starchasers.com
%3FCode%3D%25%25Code%25%25">Web site</a> ]]>
           </VALUE>    
  </PERSONALIZATION>  

Example 2 – Email Message Hyperlink HTML (source view of the email after sending)

ex3-email_msg_hyperlink_html.png

Example 3 – Browser Redirect URL with Query String

http://www.starchasers.com/?Code=441605

Query String Parameters

Query string links follows the standard query string ‘name-value pair’ formatting
rules.

Formatting Rules

  • Separate the parameters from the address with a question mark (?).
  • Separate one parameter from the next with an ampersand (&). For example, ?m=4&x=5.
  • Separate the name-value pairs with an equal sign (=). For example, ?m=12345.
  • XML is case-sensitive and UTF-8 uses different symbols for uppercase and lowercase characters.

Example

http://www.starchasers.com/?code=123…ccount=8016428

DLL Query String Parameters

Here’s a list of DLL query string parameters and their values:

Table 1. Host Server URLS
Name Value

Server URL

URL of the clickthrough tracking (CTT) servlet on the server. See table on page 55 for a list of Server URLs for each pod.

?m

Mailing ID for the submission (system substitution – user supplies placeholder only).

&r

Recipient ID for the submission (system substitution – user supplies placeholder only).

&b

Mailing body type:

0 – HTML

1 – <Deprecated. Formerly the AOL body type>

2 – TEXT

3 – Click to View

&j

Job ID for the submission that is being sent (system substitution – user supplies placeholder only)

&k

Name for the link that is specified by the link creator. Often used to differentiate between multiple links in a mailing with a descriptive name, making it easy for users to identify. For
example, “&k=left_banner_link” “&k=bottom_left_logo_link” “&k=sponsor_Sleepwell”

&kt

Link type:

1 – Regular hyperlink. ( can track.)

12 – Personalized hyperlink. Link that has a personalization field unique to each contact. The link name must be the same for every contact, but
substitutes the value based on the contact. ( can track.)

5 – Clickstream hyperlink. A link that opens a browser window to a website and then provide tracking for various actions that are performed at that website. ( can track.)

&kd

Contains the encoded URL to use as the foundation of the URL to process, send to the contact’s browser, and redirect. Important: You must encode this portion of the query string or the personalization does not work.

&kx=1

Link cross-reference. Specify whether to use the KD you entered above (or to default to the database).

0 – Ignore KD link above and default to database (not preferred).

1 – Ignore database and use destination specified in KD above (typical).

Example 1 – Sample XML Submission with DLL-Encoded Links and Personalization

<XTMAILING>
<CAMPAIGN_ID>numeric CAMPAIGN id</CAMPAIGN_ID>
<TRANSACTION_ID>TRANS-1234</TRANSACTION_ID>
<SHOW_ALL_SEND_DETAIL>false</SHOW_ALL_SEND_DETAIL>
<SEND_AS_BATCH>false</SEND_AS_BATCH>
<NO_RETRY_ON_FAILURE >false</NO_RETRY_ON_FAILURE>
<SAVE_COLUMNS>
<COLUMN_NAME>ACCOUNT_ID</COLUMN_NAME>
</SAVE_COLUMNS>
<RECIPIENT>
<EMAIL>person@domain.com</EMAIL>
<BODY_TYPE>HTML</BODY_TYPE>
<PERSONALIZATION>
<TAG_NAME>ACCOUNT_ID</TAG_NAME>
<VALUE>807</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>TRANSACT_MAIL_BODY</TAG_NAME>
<VALUE>
<![CDATA[
<p>Click this link: <a href="
http://recp.mkt32.net/ctt?m=%%MAILIN...count_ID%25%25">link</a><p>
]]>
</VALUE>
</PERSONALIZATION>
</RECIPIENT>
</XTMAILING>

In the sample XML submission above, the sections relevant to DLL Link Tracking are highlighted in bold and explained as follows:

  • The <SAVE_COLUMNS> element contains the personalization element. By
    placing the “ACCOUNT_ID” personalization in the<SAVE_COLUMNS> section, stores the value for this field in the database that is associated with the Transact Automated Message Group in
    along with system field data for the record.
  • The <PERSONALIZATION> element contains the “ACCOUNT_ID”
    personalization element with its corresponding value for the contact of this Transact email. When the mail is sent to the contact, “ACCOUNT_ID” database column is updated with the value (“807” for this record) along with the system columns.
  • The Dynamic Link Leader-encoded URL is the URL placed in the mailing. When the contact clicks the link, it resolves to the tracking servlet. The servlet processes the URL parameters and updates the tracking data. Personalization substitutions are made and the contact’s browser is redirected to the correct URL destination specified in the “&kd” parameter.
Note: You can also provide static personalization information through a Template and use Tracking.

Encoding the KD parameter

You must encode the KD portion of the query string with non-alphanumeric characters.

Important: If you do not encode with non-alphanumeric characters, identical
personalization information is sent in every email. Characters (such as question marks, equal signs, and percent symbols) are encoded using the UTF-8 character set equivalents in hexadecimal, preceded by the percent symbol (%). See the examples and encoding table below for more information.

Unencoded string

kd=http://www.spdemo.com?AccountID=%%Account_ID%%">link</a>

Encoded string

kd=http://www.spdemo.com%3FAccountID%3D%25%25Account_ID%25%25">link</a>

UTF-8 (Unicode) hexadecimal encoding substitutions for non-alphanumeric characters:

Character Hexadecimalequivalent Character Hexadecimalequivalent
! 21 , 2c
22 2d
# 23 . 2e
$ 24 / 2f
% 25 : 3a
& 26 ; 3b
27 < 3c
( 28 = 3d
) 29 > 3e
* 2a ? 3f
+ 2b @ 40

For more information, see
http://www.utf8-chartable.de/ or http://www.unicode.org.

Clicked Tracking Hyperlink with Personalization Limitations

When you are using dynamic hyperlinks in the XML document, note the following:

  • You must specifically state that you want to save the XML columns that contain the data in the database. The server performs the substitutions for personalized links by using data in the saved columns.
  • When you are placing hyperlinks in CDATA, insert the corresponding personalization values in the XML Personalization section.
  • You must completely compose XML-embedded hyperlinks on your system.
  • You must provide a default value in case the hyperlink personalization is incomplete either because it was not submitted in the XML, or information is not yet synchronized due to a slight delay with the server.
  • Limit personalization strings to 4000 characters. Data and markup over 4000 characters is not stored.
    Note: Older databases can have a 255-character limit. Check with
    Technical Support for more information if this is an issue.
  • The number of links that are included in the XML submission is not limited.
  • Campaign Automation does not track improperly formed hyperlinks in the XML. For example, do not use personalization that is unique to your system without following the personalization requirements in this section. Avoid using such personalization as it cmight cause server issues and delays.
Note: does not return an error code for this issue.

XML Submit Document Schema

We provide the following schemas for Transact for illustrative purposes only. We do not
recommend copying schemas and using them for XML validation in a production environment without thorough testing.

Submit Document Schema Rev 1.2

<xsd:schema xmlns:xt=
"http://www.silverpop.com/XTMailing" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
elementFormDefault="unqualified" attributeFormDefault="unqualified">
<xsd:element name="XTMAILING">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="CAMPAIGN_ID" type="xsd:long"/>
<xsd:element name="TRANSACTION_ID" 
type="xsd:string" minOccurs="0"/>
<xsd:element name="SHOW_ALL_SEND_DETAIL" 
type="xsd:boolean" default="false" minOccurs="0"/>
<xsd:element name="SEND_AS_BATCH" 
type="xsd:boolean" default="false" minOccurs="0"/>
<xsd:element name="NO_RETRY_ON_FAILURE" 
type="xsd:boolean" default="false" minOccurs="0"/>
<xsd:element name="SAVE_COLUMNS" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="COLUMN_NAME" 
type="xsd:string" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="RECIPIENT" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="EMAIL" type="xsd:string"/>
<xsd:element name="BODY_TYPE" type="xsd:string"/>
<xsd:element name="PERSONALIZATION" 
minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="TAG_NAME" type="xsd:string"/>
<xsd:element name="VALUE" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

XML Submit Element Definitions

This article contains details about General Submit Elements and Recipient and Content
Elements.

General Submit Elements

Note: Campaign ID is also known as the Group ID in .
  • XTMAILING
  • CAMPAIGN_ID
  • TRANSACTION_ID​
  • SHOW_ALL_SEND_DETAIL
  • SEND_AS_BATCH
  • NO_RETRY_ON_FAILURE
  • SAVE_COLUMNS
  • COLUMN_NAME
Element: XTMAILING Usage: Required Sequence: Top-level
Description: Top-level element encapsulating the XML document that provides the generation and sending of transactional emails.
Element type: N/A Data type: N/A Default Value: N/A Limit: N/A
Values: N/A
Occurrence indicators None
Attributes None
Note: N/A
Example:
<XTMAILING>Elements</XTMAILING>
Element: CAMPAIGN_ID Usage: Required Sequence: after XTMAILING
Description: Transact uses the Campaign ID to map the content to the Group of Automated Messages.
Element type: Complex Data type: string Default Value: N/A Limit: 255 characters
Values: Number of the Group that is used for the mailing, which must be a valid ID number that is assigned to the mailing.
Occurrence indicators None
Attributes None
Note: A single XML document cannot submit to multiple IDs.
Example:<CAMPAIGN_ID>300401</CAMPAIGN_ID>
Element: TRANSACTION_ID Usage: Optional Sequence: after CAMPAIGN_ID
Description: Optional parameter that is used by the sender for uniquely identifying a transaction. The value that is specified is returned in the Response Document if used in the original request.
Element type: Complex Data type: string Default Value: N/A Limit: 255 characters
Values: Transaction ID number to be used for the mailing (can be any Transaction ID number that is assigned by the sender).
Occurrence indicators

minOccurs=”0″

Values:

0 = element is optional

Attributes None
Note: A single XML document cannot submit more than one Transaction ID.
Example:
<TRANSACTION_ID>TRANS-1234</TRANSACTION_ID>
Element: SHOW_ALL_SEND_DETAIL Usage: Optional Sequence: after TRANSACTION_ID
Description: Sets the level of logging for all emails that are sent in the current submission.
Element type: Complex Data type: Boolean Default Value: false Limit: N/A

Values:

true = Complete logging of all emails that are sent for the current submission.

false = Response document contains only logged information for emails with errors.

Occurrence indicators

minOccurs=”0″

Values:

0 = element is optional

Attributes None
Note: None
Example:<SHOW_ALL_SEND_DETAIL>false</SHOW_ALL_SEND_DETAIL>
Element: SEND_AS_BATCH Usage: Optional Sequence: after SHOW_ALL_SEND_DETAIL
Description: Notifies Transact that it does not need to send the submission in real time; it can run it as a batch job.
Element type: complex Data type: Boolean Default Value: false Limit: N/A

Values:

true = Send as batch job

false = Send in real time

Occurrence indicators

minOccurs=”0″

Values:

0 = element is optional

Attributes None
Notes:

  • If you do not use this element, Transact sends the submission in real time.
  • For HTTP submissions, we recommend singular (not batch).
  • If SEND_AS_BATCH is true, then the NO_RETRY_ON_FAILURE element
    must be false to send as batch.
Example: <SEND_AS_BATCH
>false</SEND_AS_BATCH>
Element: NO_RETRY_ON_FAILURE Usage: Optional Sequence: after SEND_AS_BATCH
Description: If the system encounters an error during the sending process (for example, PMTA failure, or is offline), it does not retry sending the message.
Element type: Complex Datatype: Boolean Default Value: false Limit: N/A

Values:

True = if an error is encountered during the sending process, do not retry send.

False = retry send as soon as the error condition has been corrected.

Occurrence indicators

minOccurs=”0″

Values:

0 = element is optional

Attributes None
Notes:

  • Will not retry submission for parsing (or other data) errors in the submitted XML, regardless of this setting.
  • If NO_RETRY_ON_FAILURE is set to true, the following message appears:

    “We are
    currently unable to process this request. Your request IS NOT being queued for a later send. There will NOT be any attempts to resend this request. Please try your request later or use an alternate send method.”

  • If NO_RETRY_ON_FAILURE is set to false, the following message appears:

    “We
    are currently unable to send your request. Your request IS BEING queued for a later send. As soon as the process is running, your request will be sent as intended.”

  • If NO_RETRY_ON_FAILURE is set to false and it fails, you get a batch.
Example: <NO_RETRY_ON_FAILURE
>false</NO_RETRY_ON_FAILURE>
Element: SAVE_COLUMNS Usage: Optional Sequence: after NO_RETRY_ON_FAILURE
Description: Optional list of column names from the recipient
elements to save to the database in .
Element type: Complex, Elements Data type: N/A Default Value: N/A Limit: N/A
Values: N/A
Occurrence indicators

minOccurs=”0″

Values:

0 = element is optional

Attributes: SAVE_TO_RESPONSE This saves the corresponding columns under the personalization elements to the response. Valid values are True or False.
Note: If you do not use this element, does not save any column names.

Example 1:

<SAVE_COLUMNS>
<COLUMN_NAME></COLUMN_NAME>
<COLUMN_NAME></COLUMN_NAME>
</SAVE_COLUMNS>

Example 2:

<SAVE_COLUMNS>
<COLUMN_NAME>TAG_A</COLUMN_NAME>
<COLUMN_NAME SAVE_TO_RESPONSE = “true”>TAG_B</COLUMN_NAME>
</SAVE_COLUMNS>
Element: COLUMN_NAME Usage: Optional Sequence: after SAVE_COLUMNS
Description: Optional column name from the recipient elements to
save to the database in .
Element type: Complex Data type: string Default Value: N/A Limit: 255 characters
Values: List of column names.
Occurrence indicators

minOccurs=”unbounded”

Values:

unbounded= no limit

Attributes None
Note: If you do not use this element, does not save any column names.
Example:
<COLUMN_NAME>NAME</COLUMN_NAME>

Recipient and content elements

  • RECIPIENT
  • EMAIL
  • BODY_TYPE
  • PERSONALIZATION
  • TAG_NAME
  • VALUE
Element: RECIPIENT Usage: Required Sequence: Top-level
Description: Top-level element for defining a mail recipient. At least one Recipient block is required per submission; however, Transact can accept more than one Recipient block per submission that maps to the same Campaign ID.
Element type: Complex, Elements Data type: N/A Default Value: N/A Limit: N/A
Values: N/A
Occurrence indicators

maxOccurs=”unbounded”

Values: unbounded= no limit

Attributes None
Note: Send in groups of ten or less for best performance by using HTTP Requests.

Example:

<RECIPIENT>
<EMAIL></EMAIL>
<BODY_TYPE></BODY_TYPE>
<PERSONALIZATION></PERSONALIZATION>
</RECIPIENT>
Element: EMAIL Usage: Required Sequence: after RECIPIENT
Description: Contains the email address to which the transactional email is sent (recipient).
Element type: Complex, Elements Data type: string Default Value: N/A Limit: 255 characters
Values: Text – email address of the recipient.
Occurrence indicators None
Attributes None
Note: None
Example:
<EMAIL>person@domain.com</EMAIL>
Element: BODY_TYPE Usage: Required Sequence: after EMAIL
Description: An optional parameter to define if this is an HTML only or TEXT only.
Element type: Complex Data type: string Default Value: HTML Limit: 255 characters

Values:

  • HTML
  • TEXT
Occurrence indicators None
Attributes None
Note: N/A
Example:
<BODY_TYPE>HMTL</BODY_TYPE>
Element: PERSONALIZATION Usage: Required Sequence: after BODY_TYPE
Description: At least one personalization block is required for providing the content for the email to be sent. Each Personalization element contains one name-value pair.
Element type: Complex, Elements Data type: N/A Default Value: N/A Limit: N/A
Values: N/A
Occurrence indicators

minOccurs=”1″

Values:

1 = at least one of them is required.

maxOccurs=”unbounded”

Values:

unbounded= (no limit)

Attributes None
Note: N/A

Example:

<PERSONALIZATION>
<TAG_NAME>TEXT</TAG_NAME>
<VALUE>text</VALUE>
</PERSONALIZATION>
Element: TAG_NAME Usage: Required Sequence: after PERSONALIZATION
Description: Specifies the name of the personalization string that is used in the body of the mailing template for the mailing.
Element type: Complex, Elements Data type: string Default Value: N/A Limit: 255 characters
Values: tag name of the corresponding field (tag) in the
Template.
Occurrence indicators None
Attributes None
Notes:

  • TAG_NAME elements can appear in any order; they are not sequenced. The order does not have to match the order that is presented in SAVE_COLUMNS nor that in .
  • The XML formatting must be exact. XML tags and fields in can be in lowercase, uppercase, or mixed case, but tags must exactly match the fields that are used in . Booleans (true, false) must be in lowercase.
Example:
<TAG_NAME>FLT_1_TRIP_TITLE</TAG_NAME>
Element: VALUE Usage: Required Sequence: after TAG_NAME
Description: Specifies the value of the corresponding TAG_NAME element.
Element type: Complex Datatype: string Default Value: N/A Limit: 255 characters
Values:

  • Text content (any)
  • CDATA

Any text or CDATA-wrapped HTML, XML, XSL, XHTML, and styles.

Occurrence indicators None
Attributes None
Notes:

  • The Transact server does not process any code (logic or transformation) placed in text or CDATA content, including anything inserted by Template fields.
  • If the text contains angle brackets (< or >), you must enclose it within a CDATA section.

Example:

<VALUE>Atlanta Hartsfield-Jackson ATL (ATL) to Salt Lake City International (SLC)</VALUE>

2 comments on"XML Submit Document"

  1. Using the XML submit, can someone share an example code for how you would submit multiple attachments within an XML submission to send emails to customers?
    If we followed the airline example, lets say someone wanted to attach a pdf of a flight ticket and a receipt… How would that code look?

    Thanks

  2. Can we customize the sender name in the xml document

Join The Discussion

Your email address will not be published. Required fields are marked *