Getting started with 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.
Prerequisites
To get started, ensure that the following prerequisites are met:
- You understand the major concepts abouthandlebars and have tested the basic features of scripting at http://tryhandlebarsjs.com/
- Your organization administrator has enabled your organization for Transact XML and Transact XML Message Scripting.
- A Transact database is created. For more information, see https://help.goacoustic.com/hc/en-us/articles/360042857094-Create-a-database
- A Transact group is created. For more information, see https://help.goacoustic.com/hc/en-us/articles/360043097514-Create-approval-groups
- You are familiar with the basics of Transact XML, the basics of message scripting, and using helpers in message scripting. For more information, see Understanding message scripting basics and Using helpers in message scripting
Follow these recommendations with message scripting:
- 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 Mailing settings of a scripted template, including fields such as Subject line, From name, From address, and Reply-to address.
Step-by-step
-
Go to Content > Create email > Email template and create the Transact email.For more information, see Create and manage email templates assigned to Transact
-
In the template, click Source and then paste the scripted template in the editor.
-
In Preview, an Enter the JSON Scripting Context panel appears when scripting is detected in the editor. Enter the JSON scripting context.
-
Click Test to ensure that the context is acceptable.
-
If you want to edit the scripting context, click Change JSON Scripting Context and then click refresh to update the preview.
-
(Optional) Use simple substitution to personalize transactional emails that include message scripting.
A simple Handlebars expression is a simple identifier. Field names inside mustaches {{ ... }} in the template match fields with exactly the same name from the script context. Matching is case sensitive with script substitutions. If there is no match, an empty string is rendered.
Note:
Nested script substitutions are not supported.
Example:
With a JSON context of {"FirstName": "Watson", "Lastname": "Smith"}
Hello, {{FirstName}}! shows as Hello, Watson!
Hello, {{FirstName}} {{LastName}}! shows as Hello, Watson Smith!
If you would like to use personalization to provide a URL value in the email body, use {{{URL}}} to submit the URL value. For Example,
{
"URL":"warming <a href=\"https://google.com\" ct="SPCLICK\"> URL</a>"
}
-
Save the email.
-
Preview the script by using the content builder or the Transact Scripting Tester.
Acoustic Campaign content builder
To preview text by using the content builder, follow these steps:
- Open the transact mailing template where you added the scripted content.
- When the scripting template is detected in the email editor, a JSON placeholder appears in the Preview panel.
- Enter the JSON scripting context in the JSON placeholder.
- If you make changes to the JSON, click the Refresh button to refresh the Preview panel with updated HTML. If you leave the content builder and return, the JSON context is not maintained.
Transact Scripting Tester
Before you can preview text by using the Transact Scripting Tester, you need the following:
-Scripted templateand Script context.
- An OAuth access token is required when you use this tool. For details, see the Getting Started with OAuth article and REST docs for OAuth Token.
Notes: - In the script template's <CAMPAIGN_ID> field, enter the Automated Message Group Id you want rendered. Do not use the active Campaign ID.
- Before previewing, save your template each time you make changes. The preview tool can only render template changes that have been saved.
To preview text by using the Transact Scripting Tester, follow these steps:
-
To open the tester, enter [yourTransactURL]/PreviewTestPage.html in your web browser. For example, if you are using Transact 1, the test url is transact-campaign-us-1.goacoustic.com/PriviewTestPage.html
-
In Test XML, paste the scripted template.
-
Paste the scripted context below the scripted template.
-
In the OAuth Access Token field, enter the OAuth token.
-
Click Post Data
-
View the response.
-
Use the XML Transact Interactive Test Page to test your transactional emails.
The tool sends a test transactional email through the Transact send engine.
Notes:
- In the script template's <CAMPAIGN_ID> field, enter the Automated Message Group Id you want rendered. The test send tool requires an active Campaign ID in the CAMPAIGN_ID field.
- To register your application and request a refresh token, see Getting Started with OAuth
- To access the REST API documentation for OAuth tokens, go to http://api-campaign-us-1.goacoustic.com/restdoc/.
- To open the XML Transact Interactive Test Page, enter [yourTransactURL]/XMLTransactInteractiveTestPage.html in a browser. For example, if you are using Transact 1, the Transact URL is http://transact-campaign-us-1.goacoustic.com/XTMail
- In Test XML, paste the scripted template.
- Paste the scripted context below the scripted template.
- (Optional) In the OAuth Access Token field, enter the OAuth token. The test send tool uses OAuth access tokens for authentication. However, if the access token is not provided, then the standard Transact IP validation is used.
- Click Post Data
- View the response.
Expected outcome
You create email messages dynamically using email scripting and send email messages to contacts.
Updated over 1 year ago