Create and send dynamic email messages using Transact XML Message Scripting

Email message scripting allows for dynamic creation of email messages to contacts. The current version of this feature focuses on transactional emails and is applicable only to XML-based Transact, i.e. HTTP and Batch. Email message scripting is largely based on Handlebars, the popular open source templating framework. While not everything is supported, custom extensions are available. Many of the basic features of scripting can be experimented with at http://tryhandlebarsjs.com/.

📘

Note:

This document assumes that you are already familiar with the basics of Acoustic Campaign Transact XML.

Recommendations

• The script context structure must match the layout of the template.
• Minimize logic in the template. If the script context structure properly matches the layout of the template, then most logic is eliminated.
• Do not use standard profile personalization in the body of scripted messages. For example, %%FirstName%%. However, you can use standard profile personalization in the Email settings of a scripted template, including fields such as Subject line, From name, From address, and Reply-to address.

Getting started withand enabling Transact XML Message Scripting

Before you can include message scripting in transactional emails, an organization administrator must enable this feature in the organization settings. Then, you can create a transactional email by using the email content builder.

To enable this feature, take these steps:

1. In Acoustic Campaign, go to Organization Settings.
2. Click Email Settings and then click Edit.
3. Select Enable Scripting.
4. Click Save.

Understanding message scripting basics

Learn about scripted templates and script context that are needed for message scripting.
Transact email message scripting requires two components to render a complete email ready for sending.

• Scripted template: An HTML document that contains both static HTML markup and the scripting code inside what are often described as mustaches{{ ... }}.
• Script context: Data that is provided to the script that renders the template's dynamic results. We recommend that you use JSON personalization fields in the script context.

Creating the Transact email using message scripting

Learn how to add a scripted template and script context to a transactional email.

Before you begin:

• Create a Transact database. For more information, see:How to create a database
• Create a Transact group. For more information, see:Create a calendar update in automated message groups

After you have created a Transact database and Transact group, follow the steps shown here:

1. Go to an Email template and create the Transact email. For more information, see:How to create an Email
2. In the template, click Source and then paste the scripted template in the editor.
   3.In Preview, an JSON Scripting Context panel appears when scripting is detected in the editor. Enter the JSON scripting context.
3. Click Test to ensure that the context is acceptable.
4. If you want to edit the scripting context, click Change JSON Scripting Context and then click Refresh to update the preview.
5. Save the email.
6. Preview the script.

JSON versus standard Transact XML personalization fields

You can use standard Transact XML personalization fields to provide the script context for many kinds of email templates. However, JSON is the preferred format. This format can be used in more complex templates, such as layouts that involve nested data or looping, and is a flexible way to model data to match the layout of even the most sophisticated templates.
Comparing personalization field formats for context data

Script context fields

The following fields are available in the script context:

• Email_ID: The active Email ID for the group of automated messages.
• FORWARD_INFO: Always set to an empty string.
• JOB_ID_CODE: The encoded version of the Job ID. In Transact, this is the same as the Report ID.
• RECIPIENT_TYPE: Always set to zero.
• RECIPIENT_ID: The URL-encoded version of the encoded Recipient ID.
• RECIPIENT_CODE:
• Email tracking level unique: The URL-encoded version of the encoded Recipient ID.
• Email tracking level unique: Set to zero.
• OPT_OUT_VERP: the value based on the Email ID, Recipient ID, Job ID, and sending opt-out domain.

Scripted template example

View an example of a scripted template that is used in message scripting. When you add a scripted template to the transactional email. The email recipient sees the scripted template in the message body.

<html>
	<header>
		<title></title>
	</header>
	<body>
Hello {{first}},
		<br/>
{{#if country }}
You are from {{country}}.
		<br/>
{{else if favnum}}
I don't know where you are from, but your favorite number is {{favnum}}.
{{else}}
Sorry, I don't know where you are from or what your favorite number is.
{{/if}}
	</body>
</html>

Script context examples

Compare examples of script contexts that are used in message scripting and view the output.

<XTMailing>
	<CAMPAIGN_ID>4503824</CAMPAIGN_ID>
	<RECIPIENT>
		<EMAIL>[email protected]</EMAIL>
		<BODY_TYPE>HTML</BODY_TYPE>
		<SCRIPT_CONTEXT>
			<![CDATA[
 {"first": "Winston",
 "country": "Canada",
 "favnum":"2"
 }
 ]]>
		</SCRIPT_CONTEXT>
	</RECIPIENT>
</XTMailing>

<XTMailing>
	<CAMPAIGN_ID>4503824</CAMPAIGN_ID>
	<RECIPIENT>
		<EMAIL>[email protected]</EMAIL>
		<BODY_TYPE>HTML</BODY_TYPE>
		<PERSONALIZATION>
			<TAG_NAME>first</TAG_NAME>
			<VALUE>Winston</VALUE>
		</PERSONALIZATION>
		<PERSONALIZATION>
			<TAG_NAME>country</TAG_NAME>
			<VALUE>Canada</VALUE>
		</PERSONALIZATION>
		<PERSONALIZATION>
			<TAG_NAME>favnum</TAG_NAME>
			<VALUE>2</VALUE>
		</PERSONALIZATION>
	</RECIPIENT>
</XTMailing>

Resulting HTML

The contexts generate the same HTML results.

<html>
	<header>
		<title></title>
	</header>
	<body> 
Hello Winston,
		<br/> 
You are from Canada.
		<br/>
	</body>
</html>

📘

Note:

The conditional logic only works with data in the JSON script context and does not work with the XML-based personalization values. Standard personalization will work when it is outside of message scripting.