Articles in this section

Getting Started with Freemarker

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.

The complete Freemarker reference guide is available at the Apache website

Table of Contents

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> 
HTML/Text Template Rendered Message
Hello, ${Recipient.FirstName}!
Hello, Joe!
${Recipient.MyCustomField}
XYZ

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>
HTML/Text Template Result
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>
Hello, Joe!
Thank you for your recent order.
Order Number: 987654321
Item: 123456
Price 25
Qty: 1
Item: 987654
Price 32
Qty: 2

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>
HTML/Text Template Result
<#list Recipient.Order.Item?sort_by("Desc") as item>
Desc: ${item.Desc}
Item: ${item.Sku}
Price ${item.Price}
Qty: ${item.Qty}
</#list>
Desc: Hammer
Item: 123456
Price 25
Qty: 1
Desc: Saw
Item: 987654
Price 32
Qty: 2
<#list Recipient.Order.Item?sort_by("number(Price)") as item>
Desc: ${item.Desc}
Item: ${item.Sku}
Price ${item.Price}
Qty: ${item.Qty}
</#list>
Desc: Hammer
Item: 123456
Price 25
Qty: 1
Desc: Saw
Item: 987654
Price 32
Qty: 2

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>
HTML/Text Template Result
${Recipient.Date}
2024-01-01
${Recipient.Date?date("yyyy-MM-dd")}
Jan 1, 2024
${Recipient.Date?date("yyyy-MM-dd")?string.short}
1/1/24
${Recipient.Date?date("yyyy-MM-dd")?string.medium}
Jan 1, 2024
${Recipient.Date?date("yyyy-MM-dd")?string.long}
January 1, 2024
${Recipient.Date?date("yyyy-MM-dd")?string.full}
Friday, January 1, 2024
${Recipient.Number}
200.257
${Recipient.Number?number}
200.257
${Recipient.Number?number?string.currency}
$200.26
${Recipient.Number?number?string.percent}
20,026%
${Recipient.Number?number?round}
200 
${Recipient.String}
ABCxyz
${Recipient.String?substring(1,4)}
BCx
${Recipient.String?upper_case}
ABCXYZ
${Recipient.String?capitalize}
Abcxyz

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> 
HTML/Text Template Result
<#setting locale="Recipient.Locale">
${Recipient.Date?date("yyyy-MM-dd")?string.full}
vendredi 1 janvier 2024
<#setting locale="us_EN">
${Recipient.Date?date("yyyy-MM-dd")?string.full}
Friday, January 1, 2024

FreeMarker Reference Resources

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

Was this article helpful?
2 out of 3 found this helpful

Comments

0 comments

Article is closed for comments.