Templates
Store email templates once and send them with variables.
Template syntax
A template has a subject, an HTML body and an optional text body. All three can contain variables. You can edit templates with a live preview in the dashboard under Templates, or manage them through the API.
| Syntax | Meaning |
|---|---|
{{ name }} | Inserts a value. HTML-escaped in the HTML body. |
{{{ name }}} | Inserts a value without escaping. Only for HTML you trust. |
{{ user.first_name }} | Dotted paths into nested objects. |
{{ name | default: "there" }} | Fallback when the value is missing or empty. |
{{#if premium}} … {{else}} … {{/if}} | Condition. |
{{#unless premium}} … {{/unless}} | Negated condition. |
{{#each items}} {{ name }} {{ @index }} {{/each}} | Loop over a list. Use {{ this }} for plain values. |
{{! note }} | Comment. Never rendered. |
If the text body is empty, MailForge derives a plain-text version from the rendered HTML.
Create a template
/api/v1/templatesRequires templates:writecurl -X POST https://mail.example.com/api/v1/templates \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Welcome email",
"alias": "welcome-email",
"subject": "Welcome, {{ name | default: \"there\" }}!",
"html": "<h1>Hi {{ name | default: \"there\" }}</h1>{{#if premium}}<p>Thanks for going premium.</p>{{/if}}<ul>{{#each items}}<li>{{ name }}</li>{{/each}}</ul>",
"sampleData": {
"name": "Ada",
"premium": true,
"items": [
{
"name": "Invite your team"
}
]
}
}'namestringrequired- 1 to 120 characters. Shown in the dashboard.
aliasstring- A stable handle to send by, such as
welcome-email. 2 to 64 lowercase letters, digits,-and_. Unique per workspace. subjectstringrequired- Subject line. May contain variables.
htmlstring- HTML body, up to 500,000 characters. At least one of
htmlortextis required. textstring- Plain-text body.
sampleDataobject- Test values used for previews. Up to 256 KB.
Response
{
"data": {
"id": "d951a62f-2564-45ff-b789-2f71d9f270fc",
"name": "Welcome email",
"alias": "welcome-email",
"subject": "Welcome, {{ name | default: \"there\" }}!",
"html": "<h1>Hi {{ name | default: \"there\" }}</h1>{{#if premium}}<p>Thanks for going premium.</p>{{/if}}<ul>{{#each items}}<li>{{ name }}</li>{{/each}}</ul>",
"text": "",
"sampleData": {
"name": "Ada",
"premium": true,
"items": [
{
"name": "Invite your team"
}
]
},
"version": 1,
"createdAt": "2026-11-20T19:37:26.929Z",
"updatedAt": "2026-11-20T19:37:26.929Z"
},
"variables": [
{
"path": "name",
"kind": "text",
"optional": true,
"fallback": "there"
},
{
"path": "premium",
"kind": "flag",
"optional": true
},
{
"path": "items",
"kind": "list",
"optional": true,
"children": [
{
"path": "name",
"kind": "text",
"optional": false
}
]
}
],
"syntaxErrors": []
}variables lists every variable the template uses. syntaxErrors lists problems such as an unclosed block. A template with syntax errors can be saved as a draft, but it cannot be sent until they are fixed. An alias that is already taken returns 409.
Send a template
/api/v1/templates/{id or alias}/sendRequires emails:sendRenders the template with your variables and queues the result like a normal email. It takes the same fields as sending an email, except that html and text come from the template.
curl -X POST https://mail.example.com/api/v1/templates/welcome-email/send \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@acme.com>",
"to": "grace@example.com",
"variables": {
"name": "Grace",
"premium": false,
"items": [
{
"name": "Add a domain"
}
]
}
}'fromstringrequired- Sender address.
tostring | string[]required- One address or up to 50.
variablesobject- Values for the template. Up to 256 KB.
subjectstring- Overrides the template subject for this send. May contain variables.
cc, bcc, replyTo, stream, tags, headers, idempotencyKey, preferredProviderId- Same meaning as when sending an email.
{
"id": "d0bc24eb-c2d4-4a51-8e80-76e4f1cde444",
"status": "queued",
"stream": "transactional",
"recipients": 1,
"scheduledAt": null,
"template": {
"id": "d951a62f-2564-45ff-b789-2f71d9f270fc",
"alias": "welcome-email",
"version": 1
}
}{
"error": "Missing template variables: name",
"template": { "id": "d951a62f-2564-45ff-b789-2f71d9f270fc", "alias": "welcome-email", "version": 1 },
"missing": ["name"]
}With an SDK
const { data, error } = await mailforge.templates.send("welcome-email", {
from: "Acme <hello@acme.com>",
to: "grace@example.com",
variables: { name: "Grace", items: [{ name: "Add a domain" }] }
});Preview a template
/api/v1/templates/{id or alias}/renderRequires templates:readRenders a template without sending anything. Without variables the saved sampleData is used.
curl -X POST https://mail.example.com/api/v1/templates/welcome-email/render \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"variables": {
"name": "Grace",
"items": [
{
"name": "Add a domain"
}
]
}
}'{
"template": {
"id": "d951a62f-2564-45ff-b789-2f71d9f270fc",
"alias": "welcome-email",
"version": 1
},
"subject": "Welcome, Grace!",
"html": "<h1>Hi Grace</h1><ul><li>Add a domain</li></ul>",
"text": "Hi Grace\n\n- Add a domain",
"missing": [],
"syntaxErrors": [],
"sendable": true
}List, update, delete
/api/v1/templatesRequires templates:readLists all templates of the workspace without their bodies.
/api/v1/templates/{id or alias}Requires templates:readReturns one template with its variables and syntax errors.
/api/v1/templates/{id or alias}Requires templates:writeChanges any of the fields from creation. Each change raises version by one. Send expectedVersion to avoid overwriting someone else's edit: if the stored version differs, the API answers 409 with code: "version_conflict".
curl -X PATCH https://mail.example.com/api/v1/templates/welcome-email \
-H "Authorization: Bearer $MAILFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": "Welcome aboard, {{ name }}!",
"expectedVersion": 1
}'/api/v1/templates/{id or alias}Requires templates:writeDeletes a template. Emails that were already queued are not affected, because a template is rendered at the moment you send it.