Gears Freemarker Macros

MessageGears provides several built-in Freemarker macros to make creating and working with your message content easier. Below is the full list of macros and their arguments, with example usage below.

  • ${Gears.recipientId()}

    • Inserts the Recipient ID provided in your recipient data directly into your content. Common use is inserting into links to help identify users in click tracking
  • ${Gears.date} and ${Gears.now}

    • Inserts today’s date into the template. Common use is inserting into links to better understand engagement attribution. Due to Freemarker date and string handling, it is necessary to add date or time parameters to these calls
      <p>Be sure to visit <a href="http://www.messagegears.com?${Gears.date?datetime?string.short}">www.messagegears.com</a> for more information.</p>

  • ${Gears.requestId}, ${Gears.correlationId()}, ${Gears.jobCategory()}

    • These macros insert the mailing-specific request, correlation, and job category into the mailing
  • ${Gears.doNotSend()}

    • Triggers a render error within the message, ensuring it will not be sent. Used during development of campaigns and in content creation
<#if Recipient.language == "EN" && Recipient.Subscribed == "true">
    <#include 'local/test_message'>
    ${Gears.doNotSend("Campaign not developed yet.")}

  • ${Gears.addDate("<number of units>","<date unit>","<Date>"}

    • Adds to a given date, making date manipulation easier
      • date units are case-sensitive and one of: YEAR,MONTH,DAY,HOUR,MINUTE,SECOND, or MILLISECOND
      • Date can take one of two forms: ‘yyyy-MM-dd HH:mm:ss’ or ‘MMM dd, yyyy’

Imagine you have a tiered rewards program, with platinum members having more time to renew their subscription than gold members. Your recipient data may look like:

    <SubscribedDate>MAR 02, 2018</SubscribedDate>
    <SubscribedDate>APR 04, 2018</SubscribedDate>

Then, a simple template may be:

<#if Recipient.MemberStatus == "Gold">
    Hey Valued Member, You have until ${Gears.addDate(90,'DAY','${Recipient.SubscribedDate}')?datetime?string.short}
<#elseif Recipient.MemberStatus == "Platinum">
    Hey Valued Member, You have until ${Gears.addDate(120,'DAY','${Recipient.SubscribedDate}')?datetime?string.short}

Which would yield a rendered template of:

Hey Valued Member, You have until 5/31/18 12:00 AM

  • ${Gears.hash("<Hashing Algorithm>","<Value to Hash>")}

    • Creates a hash of its argument, typically used in click tracking and webpage reporting. Most common hashing algorithms are supported, including SHA-101, SHA-256, SHA-384, SHA-512, and md5.
<a href="https://messagegears.com/${Gears.hash("SHA-256","${Recipient.EmailAddress}")}">Sample Link</a>


<a href="https://messagegears.com/f24f7f4ce818ff42c4430dd137e4b5e0">Sample Link</a>

  • ${Gears.microsite()} and ${Gears.isMicrosite()}

    • Used to generate and work with content in a recipient’s browser instead of the mailing
  <#if Gears.isMicrosite?c == 'false'>
  Hey ${Recipient.FirstName}, your Account Balance is ${Recipient.AccountBalance}
  Hey ${Recipient.FirstName}, you account balance is available at: <a href="https://www.mysite.com/accountbalance">Your Account Page</a>
    <#if Gears.isMicrosite?c == 'false'>
    <a href="${Gears.microsite()}">Click Here to view this message in a browser.</a>
        You are viewing this email in your browser.

  • ${Gears.isForwardToAFriend()}

    • A boolean value, similar to isMicrosite, that displays whether or not content is being used in a forward to a friend mailing
  • ${Gears.track(link,link_id,link_name,url_append}

    • Used to manually track links, to be used in advanced use cases in which MessageGears Autotrack process would not suffice
  • ${Gears.deepTracklink,link_id,link_name,url_append}

    • Create and track a deep link - used as part of our Deep Linking offering
  • ${Gears.beacon}

    • Manually inserts the open beacon in a mailing
  • ${Gears.unsubscribe}

    • Inserts and unsubscribe link into a mailing
  • ${Gears.microsite}

    • Generated a microsite, to allow recipients to view email content in browsers
  • ${Gears.replyToAddress()}

    • Generates the reply to address to be used in Reply Mail Management

  • ${Gears.recipientLinkToken()}

    • Generates a recipient token which can identify a recipient that received a mailing

  • ${Gears.sequenceAppend()}

    • Generates a continued concatenation of sequences. This method is much faster than using the FreeMarker expression ‘+’ to concatenate sequences and allows for appending items to a sequence inside a loop.
  <#assign my_seq = [] />
  <#list 1..2000 as x>
    <#assign my_seq = Gears.sequenceAppend(my_seq, -x + 2001) />