Purpose
Flowmailer supports the use of templates, allowing you design and send beautiful e-mails without having to build them in your source systems. Users have full control over their templates by editing HTML or using our WYSIWYG Quick editor for basic editing. We also provide full design, HTML and template scripting services to provide working solutions.
Our templates are based on the Freemarker template engine, which allows for template logic ranging from simple to very complex. Personalization, conditional content, (nested-) loops and much more. Flowmailer adds it's own functions such as <@onlineLinkUrl /> to make working with e-mail easier. Are you a developer? Just convert your existing in-memory order to JSON and send it to Flowmailer, we'll send a nice order confirmation to the customer.
Flowmailer also has unique capabilities in re-using content from the message that the source sends. This enables our customers to send great looking e-mails without having to change how the source system sends e-mail. We can just wrap the entire message with a header and footer or select specific parts (or even specific fields) from the original message.
Quick editor
Apart from the complex logic that our templates can contain, many templates are mostly just text and images with some embedded variables. Flowmailer allows for editing those parts of templates without any code editing at all, using our visual Quick editor.
Template engine
Freemarker
Rather than reinventing the wheel, Flowmailer chose to integrate the well known and freely available Freemarker engine as a basis for our templates. This means most of the syntax and built-ins supported by Flowmailer templates can also be found in their documentation. Flowmailer adds specific functions that are designed to help Flowmailer usecases, such as including 'view online' links and marking regions as editable using our Quick Editor.
Applicability
Flowmailer supports templates in many situations. The most obvious one being HTML templates. But also, anywhere we want to make something more flexible, we use templates. For example, you can use all template functions described on this page for a Subject FlowStep, allowing you to use variables there or even add some conditional logic. Other places we have full template support include Text templates (also for SMS) and URLs settings in the External Content and External Data FlowSteps.
Please be aware that templates enable great flexibility, but you can also easily break things. Be careful when editing templates that are actively used. Flowmailer will verify the validity of templates when you save them, but some things can only be evaluated at runtime. If you do break something and cause an error, Flowmailer will send the affected messages to the "Held messages" list and raise a notification. You can then read the error message, fix the problem and choose to retry the held messages.
Basic Usage
Variables
You can use variables to store information such as text and numbers, but also as a reference to other structures such as a list. Variables can be referenced in templates, for instance to print text in a certain place. All data available in the context of a Flow are made available as variables for use in templates. When the source sends text called 'firstName', this code would print the contents:
${firstName}
In some cases, you might want to access variables that are nested in a structure called a 'hash'. For instance when you have an order confirmation and you need its id. This is how you get it:
${order.id}
Alternate/default values
Usually, the next question is: "What if the variable is missing?". Good question! Basically, we want you to make explicit decisions on what needs to happen when certain data is missing when you're sending a message. That's why all used variables are mandatory and will result in an error when missing. You can change this behavior by adding an exclamation mark: !. You can also, optionally, provide an alternate value:
Dear ${firstName!"customer"},
If the firstName variable is missing, the alternate value will be printed:
Dear customer,
If
If conditions can be used to make parts of your template conditional. Content and template logic (for instance another if) can be mixed within the conditional block. For instance, if you only want to display shipping information if relevant:
<#if shippingMethod == "regular">
Your order will ship as soon as possible!
</#if>
If statements can also contain multiple conditions and have "elseif" and "else" clauses. Please refer to the Freemarker documentation for more examples.
List
If you have a list of items, for instance an order containing order lines, you can use the list directive to handle them one by one. This is often used in conjunction with HTML lists or tables, where each item represents a new row:
<table>
<#list order.lines as line>
<tr>
<td>${line.description}</td>
<td>${line.amount}</td>
</tr>
</#list>
</table>
Original Content
Retrieving body
For basic 'wrapper'-style templates, you often just want the original message body, and place it somewhere in your template. You would need the following code to do so:
<html>
<body>
Insert original body here:
<@extractFromOriginal />
</body>
</html>
By default, Flowmailer will search for the <body></body> contents in the first HTML message part. If missing, the first Text part will be used, enclosed by <pre></pre> tags.
Extracting elements
It's also possible to use CSS selectors to find specific elements from the original message. Most types of CSS3 selectors documented by the W3C should be supported. We will list some often-used examples here:
Selecting an element with ID 'someid':
<@extractFromOriginal selector="#someid" />
Selecting whatever is contained (text?) in the second table row, second cell, enclosed by a font tag:<@extractFromOriginal selector="tr:nth-child(2) td:nth-child(2) font" />
Selecting the second cell from table rows containing specific text ('Field Name:'):<@extractFromOriginal selector="tr:contains(Field Name:) > td:nth-of-type(2)" />
Element styling (advanced)
In addition to regular templates and original content extraction, Flowmailer also allows you to change content styling on the fly. This is often done in conjunction with other templates, to 'preprocess' elements to first make the content fit the style guide you want and apply a specific template as a second step.
We do this by traversing the DOM tree using Freemarkers built-ins for nodes. Each macro in the code below represents a change in styling, by setting the attributes we want.
<#macro h1>
<h1 style="color: red;"><#recurse></h1>
</#macro>
<#macro a><a href="${.node.@href}" style="color: blue; ><#recurse></a></#macro>
<#macro img></#macro>
<#macro @text>${.node?html}</#macro>
<#macro @element><#t>
<${.node?node_name}<#t>
<#list .node.@@ as attribute><#t>
${" "}${attribute?node_name?html}="${attribute?html}"<#t>
</#list><#t>
<#t>
<#t><#recurse>
<#t></${.node?node_name}>
<#t></#macro>
<html>
<body>
<#assign doc=extractNodesFromOriginal()/>
<#recurse doc>
</body>
</html>
The code above effectively replaces the message HTML body with a reconstructed one. In doing so we make the following changes:
- All h1 texts are now red and lose all other inline styling
- All links are now blue, otherwise only retaining their href attribute
- All images are removed
Please note that creating element styling templates are considered an advanced topic and should be avoided by most users.