Skip to main content

Template Engine

We have a Handlebars-based template engine that allows you to create dynamic email templates. This engine supports a wide range of features to help you customize your emails effectively.

  • Variables: Define variables in your templates that are replaced with actual values when the email is sent.
  • Conditionals: Use conditional statements to include or exclude parts of the template based on certain conditions.
  • Loops: Iterate over collections (arrays, maps, slices, or structs) to generate dynamic content.
  • Custom Helpers: Enhance your templates with custom logic for formatting, comparisons, and more.

Depending on your template_data object, you can use simple variables, expressions, or even nested objects and arrays to create complex templates.

Built-in & Custom Helpers

In addition to Handlebars built-in helpers (if, unless, each, with, lookup, etc.), we've registered several custom helpers for your convenience:

HelperUsage ExampleDescription
eq{{#if (eq status "active")}}...{{/if}}Returns true if two values are equal.
ne{{#if (ne role "admin")}}...{{/if}}Returns true if two values are not equal.
gt{{#if (gt amount 10)}}...{{/if}}Returns true if first value is greater than second (numbers only).
lt{{#if (lt score 50)}}...{{/if}}Returns true if first value is less than second (numbers only).
gte{{#if (gte amount 100)}}...{{/if}}Greater than or equal comparison (numbers only).
lte{{#if (lte score 40)}}...{{/if}}Less than or equal comparison (numbers only).
and{{#if (and a b)}}...{{/if}}Logical AND. Returns true if both are true.
or{{#if (or a b)}}...{{/if}}Logical OR. Returns true if either is true.
not{{#if (not is_disabled)}}...{{/if}}Logical NOT. Returns true if the argument is false.
uppercase{{uppercase name}}Converts a string to uppercase.
lowercase{{lowercase email}}Converts a string to lowercase.
capitalize{{capitalize city}}Capitalizes the first letter of the string.

If you need additional custom helpers, you can request them via our support channels, and we'll get coding!

Example Template

Hello {{capitalize first_name}} {{uppercase last_name}},

{{#if (eq status "active")}}
Your account is active!
{{else}}
Please activate your account.
{{/if}}

{{#each orders}}
- Order #{{id}}: ${{amount}}
{{/each}}

Sample template_data

A sample template_data object that would work with the above template might look like this:

{
"first_name": "john",
"last_name": "doe",
"status": "active",
"orders": [
{ "id": 101, "amount": 12.50 },
{ "id": 102, "amount": 21.00 }
]
}

Rendered Output

When the above template is processed with the provided template_data, the output would be:

Hello John DOE,

Your account is active!

- Order #101: $12.5
- Order #102: $21

Error Handling

If there are any errors during template rendering, such as missing variables or syntax issues, the email will not be sent. Instead, the API will return an error response indicating the problem and the specific line number where the error occurred. This helps you quickly identify and fix issues in your templates.

For example:

{
"success": false,
"message": "We were unable to compile the template: Parse error on line 130:Lexer error\nToken: Error{\"Unexpected character in expression: '}'\"}",
"data": null
}