FreeMarker Template Language

Overview

MessageGears uses an open source Web Template Language called FreeMarker to enable personalization of the email content including the HTML, Subject Line, Text, etc. FreeMarker allows you to reference the data provided in your Recipient XML in order to personalize your email content.

Table of Contents

• Simple Personalization
• Click Tracking
• Unsubscribe Links
• Hosted Email Content
• Looping
• Sorting
• Formatting Numbers, Strings, and Dates
• Localization
• Reference Resources

Simple Personalization

MessageGears allows you to personalize your email content (HTML, Text, Subject Line, etc.). You simply reference items, by name, from your recipient XML data.

Recipient XML

<Recipient>
 <EmailAddress>joe@company.com</EmailAddress>
 <FirstName>Joe<FirstName>
 <MyCustomField>XYZ</MyCustomField>
<Recipient> 

Hello, ${Recipient.FirstName}!

${Recipient.MyCustomField}

Click Tracking

You can automatically make all links in a message trackable by setting the "autotrack" parameter to "true" in your API call.

HTML/Text Template

Click <a href="${Gears.track("http://www.myhomepage.com", "Home Page")}">here</a> to go to our home page.

The first parameter is the target URL. The second parameter is optional and creates a label that is also recorded as part of the click activity.

Unsubscribe Links

You can optionally allow MessageGears to manage un-subscription data for you. When a user clicks on an unsubscribe link they will be prompted to confirm their opt-out. If they confirm, you will be sent an "unsubscribe" event in your activity data.

HTML/Text Template

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

Hosted Email Content

Microsites are hosted versions of email messages. They are typically used to allow the email recipient to launch and view their email message in a browser if they are having difficulty viewing it in their email reader. When a microsite link is clicked in a message, a browser window will open and the fully personalized version of the HTML content of their email message will be rendered as a web page.

HTML/Text Template

Click <a href="${Gears.microsite()}">here</a> if you are having trouble viewing this message.

Looping

Recipient XML

<Recipient>
 <EmailAddress>joe@myisp.com</EmailAddress>
 <FirstName>Joe</FirstName>
 <Order>
 <OrderNumber>987654321</OrderNumber>
 <Item>
 <Sku>123456</Sku>
 <Price>25</Price>
 <Qty>1</Qty>
 <Desc>Hammer</Desc>
 </Item>
 <Item>
 <Sku>987654</Sku>
 <Price>32</Price>
 <Qty>2</Qty>
 <Desc>Saw</Desc>
 </Item>
 </Order>
</Recipient>

Hello, ${Recipient.FirstName}!
Thank you for your recent order.
Order Number: ${Recipient.Order.OrderNumber}
<#list Recipient.Order.Item as item>
Item: ${item.Sku} 
Price ${item.Price} 
Qty: ${item.Qty}
</#list>

Sorting

Recipient XML

<Recipient>
 <EmailAddress>joe@myisp.com</EmailAddress>
 <FirstName>Joe</FirstName>
 <Order>
 <OrderNumber>987654321</OrderNumber>
 <Item>
 <Sku>987654</Sku>
 <Price>32</Price>
 <Qty>2</Qty>
 <Desc>Saw</Desc>
 </Item>
 <Item>
 <Sku>123456</Sku>
 <Price>25</Price>
 <Qty>1</Qty>
 <Desc>Hammer</Desc>
 </Item>
 </Order>
</Recipient>

<#list Recipient.Order.Item?sort_by("Desc") as item>
Desc: ${item.Desc}
Item: ${item.Sku} 
Price ${item.Price}
Qty: ${item.Qty}
</#list>

<#list Recipient.Order.Item?sort_by("number(Price)") as item>
Desc: ${item.Desc}
Item: ${item.Sku}
Price ${item.Price}
Qty: ${item.Qty}
</#list>

Formatting Numbers, Strings, and Dates

Recipient XML

<Recipient>
 <EmailAddress>joe@myisp.com</EmailAddress>
 <Date>2024-01-01</Date>
 <Number>200.257</Number>
 <String>ABCxyz</String>
</Recipient>

${Recipient.Date}

${Recipient.Date?date("yyyy-MM-dd")}

${Recipient.Date?date("yyyy-MM-dd")?string.short}

${Recipient.Date?date("yyyy-MM-dd")?string.medium}

${Recipient.Date?date("yyyy-MM-dd")?string.long}

${Recipient.Date?date("yyyy-MM-dd")?string.full}

${Recipient.Number}

${Recipient.Number?number}

${Recipient.Number?number?string.currency}

${Recipient.Number?number?string.percent}

${Recipient.Number?number?round}

${Recipient.String}

${Recipient.String?substring(1,4)}

${Recipient.String?upper_case}

${Recipient.String?capitalize}

Localization

Using the localization features requires you to set the locale variable. The local variable consists of the ISO-639 two character language code (lower case), followed by the ISO-3166 two character country code (upper case) in the following format: xx_XX. For example, UK English would be "en_UK".

Recipient XML

<Recipient>
<EmailAddress>joe@myisp.com</EmailAddress>
<Locale>fr_FR</Locale>
<Date>2024-01-01</Date>
<Number>200.257</Number>
</Recipient> 

<#setting locale="Recipient.Locale">
${Recipient.Date?date("yyyy-MM-dd")?string.full}

<#setting locale="us_EN">
${Recipient.Date?date("yyyy-MM-dd")?string.full}

FreeMarker Reference Resources

• Directives/Command Syntax
• String Functions
• Date Functions
• Numeric Functions
• XML Processing

Optionally, you may also use the Apache Velocity templating language.