Message Templates

A template not only makes it possible to send pre-defined content that can be easily previewed and proofed, but it’s easy to build on that make parts dynamic using placeholder values, repeating sections, or more.

Data introduced into the template can be set globally, or personalized for each individual receiving the content.

Templates can be defined per-project using the “Message Templates” tab, or they can be sent as part of the API payload in the "content" section.

Variables / Placeholders

Simple placeholders within the content look like {{variable_name}} where the variable name is all lower-case. These represent values that are substituted when the template is rendered out.

For an example document:

Your {{delivery_type}} order will be ready for {{delivery_method}} in {{time}}.

The content to render this out should look like this when expressed as JSON:

{
  "delivery_type": "express",
  "delivery_method": "pick-up",
  "time": "two hours"
}

This results in a final output of:

Your express order will be ready for pick-up in two hours.

Where encoding for a particular context is necessary there are some modifiers that can be applied:

• {{&variable}} will render the value escaped for HTML, rendering any <, > or & characters as their respective HTML entities. This can make safe any user-supplied values.
• {{$variable}} will render the value escaped for use in JavaScript, suitable for use as a variable or in a small script.
• {{.variable}} will render the value escaped for use in CSS, such as in a class or id attribute of an HTML element or within inline CSS styles.
• {{%variable}} will render the value escaped for use in a URI such that it can be used as a URL path component or query-string value.
• {{=variable}} will render the value as-is, without any escaping, ignoring any default escaping that would have been applied.

When defining template content as HTML, either as part of the "text/html" section of "content" on an API call or through the “Message Templates” editor, all values will be escaped for HTML by default. This can be skipped if necessary to introduce raw content by using the = prefix.

Plain-text templates have no default escaping applied. Variable values are placed as-is unless one of these modifier flags is used.

Repeating Sections

It’s often the case that part of the content will take on a repeating form where the same treatment is applied to one or more values. For example, a receipt might look like this:

Amount / Item / Delivery Date
{{:items}}
{{price}} / {{desc}} / {{delivery_date}}
{{/items}}

Tags of the form {{:section_name}} are used to define the beginning of a section. The end of a section is declared with {{/section_name}}, or {{/}} for brevity.

To render out this template with a list of items, an array of values is supplied:

{
  "items": [
    {
      "price": "$12.95",
      "desc": "Pigeon Mug",
      "delivery_date": "Thursday"
    },
    {
      "price": "$6.95",
      "desc": "Stamps",
      "delivery_date": "Friday"
    },
    {
      "price": "$2.95",
      "desc": "Cloth Bag",
      "delivery_date": "Thursday"
    }
  ]
}

When these values are applied to the template the resulting output looks like:

Amount / Item / Delivery Date
$12.95 / Pigeon Mug / Thursday
$6.95 / Stamps / Friday
$2.95 / Cloth Bag / Thursday

A variant on the section tag is a “no data” alternative of the form {{^section}} that is be rendered if no content was found:

Amount / Item / Delivery Date
{{:items}}
{{price}} / {{desc}} / {{delivery_date}}
{{/items}}
{{^items}}
No items are scheduled for delivery.
{{/items}}

This content is shown if there is no variable named items or the variable is an empty array. Example content:

{
  "items": [ ]
}

As that array is empty, the resulting output looks like:

Amount / Item / Delivery Date
No items are scheduled for delivery.

For brevity it’s also possible to supply the section arguments as an array of arrays. The order in the array must match the order they appear in the section content:

{
  "items": [
    [ "$12.95", "Pigeon Mug", "Thursday" ],
    [ "$6.95", "Stamps", "Friday" ],
    [ "$2.95", "Cloth Bag", "Thursday" ]
  ]
}

As API call size is often a factor, this more compact form can significantly reduce the amount of content that needs to be supplied to correctly render the template.

Variable Presence/Absence Tests

Several boolean options are available to conditionally display content if/when it is defined. This makes templates adapt to the type of data supplied.

A typical example can test for the presence of a variable and display additional content if it is found:

Thank you for placing your order.
{{?express_time}}
This is an express order! You should receive it in {{express_time}} or less.
{{/express_time}}

Where the supplied values look like this:

{
  "express_time": "twenty minutes"
}

The resulting content looks like:

Thank you for placing your order.
This is an express order! You should receive it in twenty minutes or less.

An alternative can be defined if a variable is not present:

Thank you for placing your order.
{{?express_time}}
This is an express order! You should receive it in {{express_time}} or less.
{{/express_time}}
{{?!express_time}}
A reminder that normal shipping times are 2-4 business days.
{{/express_time}}

Where the second ?! section will show up if no express_time value could be found.

If that value is omitted the resulting content looks like:

Thank you for placing your order.
A reminder that normal shipping times are 2-4 business days.

Comments

It can be helpful to include comments in templates for a variety of reasons:

(C) Emailtec Ltd.{{! FIX: Company should be a variable }}

These are stripped from the final output:

(C) Emailtec Ltd.