Skip to main content

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.

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 TemplateRendered 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.

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 TemplateResult
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 TemplateResult
<#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 TemplateResult
${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 TemplateResult
<#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.