Creating and Managing Templates

Overview

The Content selection of Accelerator allows MessageGears users to create and manage Templates as well as global snippets (formerly Shared Content). 

A Template is constructed of the HTML, text, and header content used to design the email message which will later be sent out from a Campaign.

Before any emails can be sent out through MessageGears Accelerator, Templates must first be created containing the desired content. Templates give you the freedom to reuse the same design in future campaigns, while populating in personalized campaign content using FreeMarker, Snippets, and global snippets.

In this article we’re going to walkthrough creating a Template in MessageGears Accelerator.

Table of Contents:

• Add a New Template
• Template Overview
• Template Settings
• Sample Recipient Data
  • Upload Recipient File for Sample Recipient Data
• Supplemental Data
• Headers
• HTML
  • HTML Source Editor
  • WYSIWYG Editor
  • Import File
  • Considerations
• Text
• Snippets
  • Add a Snippet
• Testing
  • Personalization (Testing & Preview)
  • Spam Filter Testing
  • Content Evaluation
  • Email Clients
  • Subject Line
• Personalization Fields (Reference)
  • Personalizable Fields
  • MessageGears Functions
  • FreeMarker Directives

Add a New Template

To add a new Template, on the Content > Template page select Create template. This will open a modal where you can name and add a description to your template. 

You should then be sent to an Overview page with a menu of options on the left side of the screen. The following guide goes through these pages step-by-step.

Template Overview

The Overview page provides a preview of the template’s design as well as important details about the template’s size, spam score, and most recent updates.

This table can be used as a quick reference for the descriptions and uses of each page. It can also be referred to via the Help option on the Overview page of the Template:

Template Settings

On the Settings page, you can update the Name and Description of the template.

Sample Recipient Data

Sample Recipient Data consists of representative personalization fields related to a recipient list, and it is used to validate personalization accuracy. When Sample Recipient Data is pulled into a Campaign, that data will be present in the previews and tests of the campaign to serve as an example of how personalization will display for that particular set of data.

Use the "Refresh sample" dropdown to select a pre-existing Recipient Data source, or select the "Upload Recipient File" option to import a CSV or XML file as the Sample Recipient Data.

In order to provide pre-existing options in the sample drop-down, there will need to be Database Queries and/or URL Data Sources in the Audience section of Accelerator created with a Data Type of "Recipient":

Upload Recipient File for Sample Recipient Data

When uploading a new Recipient File, there are a few different options and different requirements for each:

• XML file requirements:
  • ends with .xml,
  • has a root element of "RecipientList"
  • each "Recipient" element has an "EmailAddress" node
• CSV or TSV file requirements:
  • required EmailAddress header
  • all other field names must contain only alphanumeric (A-Z 0-9) values with no special characters
  • ends with .csv or .tsv
  • file has properly named headers:
  • all file rows contain the same number of elements
• Compressed file
  • ZIP (ending in .zip)
  • GZIP (ending in .gz or .gzip)
  • ZLIB (files ending in .zlib or .dzip)
  • full name should end with the original file type extension, and then the compression extension (i.e. a zip file containing an xml file named sample-recipients would be sample-recipients.xml.zip)
  • Beneficial if you have a large number of sample recipients.
  • Currently supported compression schemas:
  • Requirements:

Supplemental Data

Suppemental data (formerly Context Data) is an optional XML source that contains data shared across all recipients for the job being processed. This data may be used to provide offer/deal content that is available for all recipients, such as "Today's Hot Travel Deals". This deal information may be presented to all recipients of the mailing, or logic within the template can be used to match the best deal/offer for each individual recipient, generated a true one-to-one message.

Supplemental Data XML can be provided in any well-formed XML structure, and elements are referenced in the template based on the format provided.

Use the “Refresh sample from datasource” dropdown to select a pre-existing Supplemental Data source, or data can be created manually by selecting the "Source" tab.

In order to provide options in the datasource drop down, there will need to be Database Queries and/or URL Data Sources in the Audience section of Accelerator created with a Data Type of "Context":

Headers

The Headers page provides a view of any existing Header settings. By clicking "Edit Headers" these can be updated to the desired From Name, From Address, Reply To Address, and Subject Line for this Template.

From Name indicates what the recipient will see in the From field of their email inbox.

From Address will be the email address the email appears to have been sent from, and this address usually corresponds directly to the From Name.

Reply To Address is often set to be the same address as From Address, but it can be set as a different address. The purpose of the Reply To Address is to indicate what email address will populate to To field when a recipient hits Reply to the email in their inbox.

Subject Line indicates what should be visible in the Subject of this email.

When adding or editing Header information, it is possible to select a pre-populated set of data if you have Sending Profiles set up in your account under Admin > Sending Profiles. To populate an existing Sending Profile, start typing the name into the Sending Profile box and it will pop up below as an option.

HTML

There are three modes of adding content to the template.

HTML Source Editor

Using the HTML Source Editor, you can paste in HTML code to create the content of the email. All of the CSS, HTML, and FreeMarker personalization content will be visible in this mode.

WYSIWYG Editor

The WYSIWYG (what you see is what you get) Editor allows editors who aren’t necessarily code-savvy to generate attractive, simple email content. The abilities of the WYSIWYG Editor in Accelerator are similar to the features found in text editing software such as font styling and adding tables.

Import File

Pre-existing HTML files can be imported directly to MessageGears Accelerator for use as a template. We recommend thorough testing of imported content to make sure it displays as expected in inboxes.

Considerations

We discourage switching between the HTML and WYSIWYG editors - for the best results, stick with one mode of editing. Personalization can be added in either mode.

To add personalization, click Personalization Fields in the left pane to open the popup, then click to copy the desired field(s) and paste it directly into the source.

Another thing to keep in mind is that MessageGears doesn’t host images or asset files for use in template content. When coding or importing, it is important that any assets included in the HTML are provided with absolute URL paths which can render in external recipient inboxes as well as internal previews and tests.

Text

The Text Content page allows for the manual or automatic creation of a plain-text version of the template.

"Create Manually" gives the creator the freedom to write custom plain-text content, while "Generate from HTML" isolates any regular text content from the HTML into a plain-text version.

Once the original selection is made, users can "Edit Text" to manually change elements of the plain-text content. Selecting "Generate from HTML" will overwrite the existing plain-text with the most recent version of the text from the HTML content. Any changes made manually to the plain-text will be lost.

Snippets

Snippets are macros, functions, HTML, or other coded content for use within a single template. Once a Snippet has been created and saved, it can be pulled into the template using FreeMarker code.

The code for including Snippets in a template looks like this:
<#include '/local/yoursnippetname'>

Add a Snippet

When adding a Snippet, you are brought to the Add Template Snippet page. Once a name is added, and a description if desired, you’ll be brought to the Snippet editor. Here you can toggle between the HTML and WYSIWYG editors, import a file, and test the snippet. Once a snippet is created, you’ll navigate back to the local (template-specific) snippets folder, and ultimately back to the template’s Overview page.

Since a Snippet is local to this template, it won’t be accessible by other templates. If you'd like to create Global Snippets for multiple templates to use, refer to the article about Adding Global Snippets.

Testing

Personalization (Testing & Preview)

On the Personalization page, you can generate a live test of the content on the page in order to test personalization rendering times and results across HTML and text content versions. Personalization relies on the Sample Recipient Data provided earlier in the process to display a preview of how the provided recipient data and personalized will render together.

Spam Filter Testing

On the Spam Filter page, you can generate and view spam scores associated with the template. This can help to identify content issues which may lead to the campaign emails landing in spam folders rather than recipients’ inboxes.

This tool is powered by SpamAssassin, a commonly used spam filter.

Content Evaluation

Running a Content Evaluation Test provides insight into how the template and content interacts with over 14 commonly used spam filters and checkpoints for email deliverability. Content Evaluation provides deeper insight into deliverability concerns than the Spam Filter test, and checks against DKIM, SPF, and other elements of email authentication.

This tool is powered by Litmus, a platform for testing email templates, content, and deliverability.

Multiple evaluations can be run, and all tests can be accessed in a list on the Content Evaluation page. A test can be left to complete and revisited later to view full results.

Email Clients

Running an Email Clients Test is similar to a Content Evaluation, but rather than evaluating the template against spam filters and authentication checkpoints, Email Clients testing will illuminate how the template will display in over 30 different email clients and on different devices. This testing tool is also powered by Litmus.

Multiple tests can be run, and all tests can be accessed in a list on the Email Clients page. A test can be left to complete and revisited later to view full results. Once a test starts to populate thumbnails, each thumbnail can be clicked to view a larger screenshot displaying the template rendered in a particular email client.

Subject Line

The Subject Line tester allows you to view how the From Name and Subject Line will display in a variety of different email inboxes.

Personalization Fields (Reference)

The bottom-most selection of the Template menu is Personalization Fields, and this item brings up a Dynamic Template Help pop-up window containing a list of click-to-copy FreeMarker and MessageGears functions to add to your content for personalization.

Clicking on an item copies the code into your clipboard, which can then be pasted into the HTML or text body of your template.

Personalizable Fields

These Personalizable Fields are frequently-used Recipient or Job related FreeMarker variables which can be used to personalize content - including links - in the template.

${Recipient.EmailAddress}

${Gears.date?date}

${Gears.requestId}

${Gears.correlationId}

${Gears.jobCategory}

MessageGears Functions

MessageGears Functions contains a set of frequently-used commands used to personalize messages with MessageGears-specific items such as a “view in browser” microsite link or an unsubscribe link. Clicking on an item copies the code into your clipboard, which can then be pasted into the HTML body of your mailing.

<a href="${Gears.track(url, [name])}">Click Here</a>

<a href="${Gears.microsite()}">Click here to view this email in a browser</a>

<a href="${Gears.unsubscribe()}">Click here to Unsubscribe</a>

FreeMarker Directives

FreeMarker Directives contains a set of frequently-used FreeMarker commands used to personalize messages. Clicking on an item copies the code into your clipboard, which can then be pasted into the HTML body of your mailing.

<#assign name=value>

<#if condition>
...
</#if>

<#list widgets as widget>
...
</#list>

<#function name param1 param2 ... paramN> 
... 
<#return returnValue> 
... 
</#function>

<#macro name param1 param2 ... paramN>
...
<#nested loopvar1, loopvar2, ..., loopvarN>
...
<#return>
...
</#macro>

<#switch value>
<#case refValue1>
...
<#break>
<#case refValue2>
...
<#break>
...
<#case refValueN>
...
<#break>
<#default>
...
</#switch>

Additional FreeMarker resources are available here:

• http://freemarker.org
• https://support.messagegears.com/hc/en-us/articles/115000851927-FreeMarker-Template-Language