Hello {{firstName}} {{lastName}}!
Click this link
{{company.name}}, {{company.adress}}
{{{signature}}}
``` **JSON Object** ```json { "firstName": "John", "lastName": "Smith", "url": "http://example.com", "company": { "name": "Best Company", "adress": "Its Address" }, "signature": "thanks!" } ``` **HTML output** ```htmlHello John Smith!
Click this link
Best Company, Its Address
thanks!
``` ### **Special characters in subject lines** If your subject line variable contains special characters (e.g. &, <, >, ", '), use triple braces `{{{ }}}` instead of double braces `{{ }}` in your template subject. Double braces escape special characters into HTML entities, which works fine in the email body but shows raw entity codes in the subject line. ### Conditional Statements #### if / else / if else Use the `if` helper for conditional block rendering. {% hint style="info" %} Should the argument return `""`, `0`, `nil`, `false`, `empty_map`, `empty_slice`, or an `empty_array`, then the block won't be rendered. {% endhint %} **Template** ```html {{#if user.isSubscribed}}Hello {{user.name}},
Thank you for subscribing to our newsletter!
{{else}}Hello {{user.name}},
We noticed that you have not yet subscribed to our newsletter. Click here to subscribe.
{{/if}} ``` **JSON test data** ```json { "user": { "name": "Jane Doe", "isSubscribed": true } } ``` **HTML email output** ```htmlHello Jane Doe,
Thank you for subscribing to our newsletter!
``` If you change the `isSubscribed` variable to `false` in JSON data, the HTML output is: ```htmlHello Jane Doe,
We noticed that you have not yet subscribed to our newsletter. Click here to subscribe.
``` {% hint style="info" %} The examples above include both `if` and `else` expressions. Of course, you can use only `if`, but it's recommendable to include `else` as well to cover the scenario where a conditional statement is `false`. {% endhint %} #### unless The `unless` block helper works like an inverse `if`. Simply put, it renders when the expression returns a `false` value. **Template** ```html {{#unless user.isSubscribed}}Hello {{user.name}},
We noticed that you have not yet subscribed to our newsletter. Click here to subscribe.
{{else}}Hello {{user.name}},
Thank you for subscribing to our newsletter!
{{/unless}} ``` **JSON test data** ```json { "user": { "name": "Jane Doe", "isSubscribed": false } } ``` **HTML email output** ```markupHello Jane Doe,
We noticed that you have not yet subscribed to our newsletter. Click here to subscribe.
``` The block helper example also contains `{{else}}` and should the `isSubscribed` variable be `true`, here's the HTML output: ```markupHello Jane Doe,
Thank you for subscribing to our newsletter!
``` #### each The `{{#each}}` helper is used to iterate over an object or array, then execute a block of code for each item. In the example below, `{{#each user.items}}` iterate over the `user.items` array, then execute the code inside the block. {% hint style="info" %} `{{this}}` helper is used as a reference to the current item in the iteration. {% endhint %} **Template** ```html {{#each user.items}}Item: {{this}}
{{/each}} ``` **JSON test data** ```json { "user": { "name": "Jane Doe", "items": ["Item 1", "Item 2", "Item 3"] } } ``` **HTML email output** ```htmlItem: Item 1
Item: Item 2
Item: Item 3
``` **Template with else block** ```html {{#each user.items}}Item: {{this}}
{{else}}No items found
{{/each}} ``` **JSON test data** ```json { "user": { "name": "Jane Doe", "items": [] } } ``` **HTML email output** ```htmlNo items found
``` #### with You can use the `with` helper to change the context in which the code block gets executed. In the example below, the `{{with user}}` block sets the context for the user object. Consequently, the `{{name}}` and `{{email}}` can be accessed directly. This is useful when you want to avoid writing long chains of nested property accessors. **Template** ```html {{#with user}}Name: {{name}}
Email: {{email}}
{{/with}} ``` **JSON test data** ```json { "user": { "name": "Jane Doe", "email": "jane.doe@example.com" } } ``` **HTML email output** ```markupName: Jane Doe
Email: jane.doe@example.com
``` **Template with else block** In the example below, the `{{else}}` clause only gets executed if there's no value within the `{{with}}` block. ```markup {{#with user}}Name: {{name}}
Email: {{email}}
{{else}}No user found
{{/with}} ``` **JSON test data** ```json { "user": null } ``` **HTML email output** ```markupNo user found
``` ### Example: Order confirmation template The following example contains the majority of Handlebars helpers explained above as well as mock JSON data, and HTML output. **Email template in HTML:** ```htmlHello {{customer.name}},
Thank you for your order! Your order number is {{order.number}}.
Your order details are:
| Product | Quantity | Price |
|---|---|---|
| {{name}} | {{quantity}} | ${{price}} |
Shipping to:
{{#with customer.address}} {{#if company}} {{company}}Your order will be shipped {{#unless order.isRush}}within 3-5 business days{{else}}within 24 hours{{/unless}}.
Total: ${{order.total}}
Thank you for shopping with us!
``` **Mock JSON data:** ```json { "customer": { "name": "John Smith", "address": { "company": "My company", "firstName": "John", "lastName": "Smith", "street": "123 Main St", "city": "Anytown", "state": "State", "zip": "ZIP", "country": "USA" } }, "order": { "number": "123456", "items": [ { "name": "Product 1", "quantity": "1", "price": "10" }, { "name": "Product 2", "quantity": "2", "price": "20" } ], "isRush": true, "total": 50 } } ``` **HTML email output:** ```htmlHello John Smith,
Thank you for your order! Your order number is 123456.
Your order details are:
| Product | Quantity | Price |
|---|---|---|
| Product 1 | 1 | $10 |
| Product 2 | 2 | $20 |
Shipping to:
My companyYour order will be shipped within 24 hours.
Total: $50
Thank you for shopping with us!
``` ### Testing templates with Handlebars In the quick tutorial below, we assume you've activated both Email Sandbox and Email API/SMTP. {% stepper %} {% step %} Navigate to **Email API/SMTP** > **Email Templates** in the menu on the left. {% endstep %} {% step %} Select your email template and click the **Integration** tab. {% endstep %} {% step %} Copy the code under the **Integration** tab (cURL, or any other based on your preference). To test the template, you only need to change the Sending API endpoint ([send.api.mailtrap.io](http://send.api.mailtrap.io/)) to Sandbox API ([sandbox.api.mailtrap.io](http://sandbox.api.mailtrap.io/)) and add the `inbox_id` to the end of the endpoint URL.