Email Template Language

By default, MessageGears uses the open source templating language, Freemarker, to provide a full-featured, non-proprietary language for personalizing your email content.


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

Hello, ${Recipient.FirstName}!
${Recipient.MyCustomField}

Rendered Message

Hello, Joe!
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

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>

Result

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

<#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>

Result

Desc: Hammer Item: 123456  Price 25 Qty: 1
Desc: Saw Item: 987654  Price 32 Qty: 2

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>2010-01-01</Date>
    <Number>200.257</Number>
    <String>ABCxyz</String>
</Recipient>

HTML/Text Template

${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}

Result

2010-01-01
Jan 1, 2010
1/1/10
Jan 1, 2010
January 1, 2010
Friday, January 1, 2010

200.257
200.257
$200.26
20,026%
200

ABCxyz
BCx
ABCXYZ
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>2010-01-01</Date>
    <Number>200.257</Number>
</Recipient> 

HTML/Text Template

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

Result

vendredi 1 janvier 2010
Friday, January 1, 2010


Freemarker Reference Resources


MessageGears uses an open source Web Template Language called Freemarker to enable email content personalization. Freemarker allows you to reference the data provided in your Recipient XML in order to personalize your email content.

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