Templates and variables
Send stored templates by slug. Built-in layouts, custom HTML templates, variables, conditionals and themes.
On this page
A template is a stored message that you reference from POST /v1/send with templateSlug (preferred, because slugs survive restores) or templateId. EmailFlare has two kinds. Browse the built-in layouts in the template gallery.
| Built-in layout | Custom template | |
|---|---|---|
| Source | 50 React Email layouts, added by the database migrations | Your own HTML and optional text body |
| Rendered with | React Email | EmailFlare’s template renderer |
| Slug | The layout name, such as welcome or otp |
Whatever you choose |
| Themes | themeId applies |
themeId is ignored |
| Editable | No | Yes |
Send a template
{
"from": "hello@yourdomain.com",
"to": "alex@example.com",
"templateSlug": "welcome",
"themeId": "ocean",
"variables": { "name": "Alex", "appName": "Acme", "loginUrl": "https://acme.com/login" }
}
Rules:
subjectin the request overrides the template’s subject.variablesfill the placeholders in the subject and the body.- When you reference a template, the request’s own
htmlandtextare ignored. - An unknown slug returns
404 Template not found. Slugs are case-sensitive. - A variable you leave out renders as an empty string. It is never printed as
{{name}}.
Built-in layouts
The layouts cover onboarding, sign-in codes and magic links, billing and receipts, subscriptions, security alerts, product notices and digests. Each layout has its own variables. The Templates page in the dashboard and the Playground list them, and show a live preview.
Layout subjects are templates too, for example Welcome to {{appName}}, {{name}}!. Pass every variable the subject uses, or the subject renders with gaps.
Themes
Set themeId to restyle a layout without editing it: default, ocean, forest, violet or slate. Custom templates ignore themeId.
Custom templates
Create them under Templates in the API workspace, or with the session API.
| Field | Required | Notes |
|---|---|---|
name |
Yes | Label shown in the dashboard. |
slug |
Yes | Lowercase letters, numbers and hyphens. |
subject |
Yes | May contain placeholders. |
htmlBody |
Yes | HTML with placeholders. |
textBody |
No | Plain-text version. |
domainId |
No | Binds the template to a sending domain. |
If the slug is taken, EmailFlare appends a short suffix, for example welcome-email-a1b2. Read the slug from the response.
GET /api/templates list
GET /api/templates/:idOrSlug fetch one
POST /api/templates create
PUT /api/templates/:id update
DELETE /api/templates/:id delete
POST /api/templates/:id/preview render with variables
These routes need a dashboard session with API access. Built-in layouts cannot be changed or deleted.
{
"name": "Order confirmation",
"slug": "order-confirmation",
"subject": "Your order {{orderId}} is confirmed",
"htmlBody": "<p>Hi {{name}},</p><p>Order <strong>{{orderId}}</strong> is confirmed.</p>",
"textBody": "Hi {{name}}, your order {{orderId}} is confirmed."
}
Placeholder syntax
Custom templates use a Handlebars-style syntax that runs without code generation, which Workers do not allow. This is what it supports:
| Syntax | Meaning |
|---|---|
{{name}} |
Insert a variable. |
{{order.id}} |
Read a nested value with a dot path. |
{{#if paid}}…{{else}}…{{/if}} |
Show a block when the value is truthy. |
{{#unless paid}}…{{/unless}} |
Show a block when it is not. |
Empty strings, false, 0, null and empty arrays count as falsy.
Things that do not work: {{#each}} loops, {{#with}} scoping, partials and custom helpers. To render a list, build the HTML rows in your application and pass them in one variable.
{
"variables": {
"rows": "<tr><td>Widget</td><td>$9.00</td></tr><tr><td>Gadget</td><td>$14.50</td></tr>"
}
}
Values are inserted exactly as given. They are not HTML-escaped, so escape any text you got from a user before you pass it.
Styling
Write styles inline in the HTML. That is the most reliable approach across email clients.
<div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
<h1 style="color: {{brandColor}};">Hello {{name}}</h1>
<p style="color: #333; line-height: 1.6;">Your order {{orderId}} is confirmed.</p>
</div>
To reuse a look across templates, pass colours and fonts as variables, or paste the same wrapper into each template body. There is no shared theme system for custom templates.
Test before you send
The Playground renders any template with sample variables, and a test key stores the finished message in the Test mailbox, so you can check it without delivering anything.