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.

SyntaxMeaning
{{ 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

POST/api/v1/templatesRequires templates:write
curl -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"
        }
      ]
    }
  }'
Body parameters
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 html or text is required.
textstring
Plain-text body.
sampleDataobject
Test values used for previews. Up to 256 KB.

Response

201 Created
{
  "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

POST/api/v1/templates/{id or alias}/sendRequires emails:send

Renders 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"
        }
      ]
    }
  }'
Body parameters
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.
202 Accepted
{
  "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
  }
}
422 response
{
  "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

POST/api/v1/templates/{id or alias}/renderRequires templates:read

Renders 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"
        }
      ]
    }
  }'
Response
{
  "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

GET/api/v1/templatesRequires templates:read

Lists all templates of the workspace without their bodies.

GET/api/v1/templates/{id or alias}Requires templates:read

Returns one template with its variables and syntax errors.

PATCH/api/v1/templates/{id or alias}Requires templates:write

Changes 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
  }'
DELETE/api/v1/templates/{id or alias}Requires templates:write

Deletes a template. Emails that were already queued are not affected, because a template is rendered at the moment you send it.