Introduction

At the core of Apostle.io is the ability to edit your email templates. To ensure you get the most out of your emails, it’s best to understand how all the pieces fit together.

There are three parts to your emails; templates, layouts and partials.

Editing a Template

When you enter the template editor, you will be presented with the editable fields on the left, and a preview of your email on the right. Drop downs are available to select a layout and the sample data for the preview to use. You can use the "HTML" and "Text" buttons to toggle between the email’s html and text body. If you leave one blank, it will not be sent - but you must supply at least one body format.

When you have completed your changes, you must hit the ‘save’ button to commit your changes. Once saved, the updates are live and any emails sent from then on will have your new changes.

Sample Data

When previewing your templates, you can add some 'sample data' to use in the template. This data is a way of previewing what your template will look like when it has data passed to it. You can add as many sample data as you like – this way you can try out different combinations of the data that may be supplied to the template. For example, you might want to see how your order complete email looks with only one item in an order, and how it looks with over 20 items!

Tip: You can create new sample data from a sent email by clicking ‘Create Sample Data from Payload’ when viewing the data payload of the email in the ‘Search’ tab.

Template Language

The 'template language' that Apostle.io uses is called Handlebars, and you may have come across it before. It’s a superset of another language called Mustache, so if you’re familiar with either of these languages then you’re well on the way to writing templates in Apostle.io. If you’re not, some of the basics are available here. For a more in depth look, please check out the Handlebars website.

Variables

A handlebars expression is surrounded by two curly braces.

1
2
3
<div> <h1>{{title}}</h1> </div>

You are not limited to flat data structures.

1
2
3
4
<div> <h1>{{user.name}}</h1> <h2>{{user.email}}</h2> </div>

Conditionals

You can add a conditional block with either the #if expression, or prepending a hash to the variable name.

1
2
3
4
5
6
7
8
9
{{#if user}} <h1>{{user.name}}</h1> {{/if}} or {{#user}} <h1>{{user.name}}</h1> {{/user}}

Loops

You can loop through items with the #each helper. Note that inside the loop, the context is that of the iterated item.

Given data in the format:

1
2
3
4
5
6
7
8
{ "items": [ { "name": "Widget Motor" }, { "name": "Widget Propeller" }, { "name": "Widget Battery" } ] }

You would loop through like so:

1
2
3
{{#each items}} <li>{{name}}</li> {{/each}}

Partials

Partials are included via their ‘slug’. If you have a partial with slug sign-off, you would include it like so:

1
{{> sign-off}}

Editing a Layout

A layout has three parts; the text body, html body and html styles. Since a layout is like a wrapper for your content, you have to make sure you include the expression for the rest of your template: {{> template}}. Without this the layout won’t know where the body of the actual template should go.

You must supply both the text and html layouts, although you can just enter the template expression if you don’t require any layout for a particular format.

Styles and Classes

You probably already know that html emails are a complicated beast and don’t like things such as tags and html classes. Apostle.io processes the styles you supply, and inlines the css when sending emails. This means that you can use ids and classes while designing your templates, and we’ll handle the hard stuff - turning it into email compliant code.

Editing a Partial

Partials have both a text and html body, each of which is optional. It‘s not recommended to include a partial in a template unless it has the format you are including it in. For example, you should not include a partial in the html body of a template if the partial does not have an html body of its own.