Templates API

How templates work

Variables

Write a variable as {{{KEY}}} anywhere in the subject, preview text or body, and declare it with a type and an optional fallback value. You can also write a fallback at the point of use: {{{PLAN|free}}}.

<p>Hi {{{NAME|there}}},</p>
<p>Your order of {{{PRODUCT}}} comes to {{{PRICE}}}.</p>
<p><a href="{{{RESEND_UNSUBSCRIBE_URL}}}">Unsubscribe</a></p>

• A variable resolves to the value passed in the send, then its inline fallback, then its declared fallback_value. A declared variable with neither must be given a value: a send that leaves it out answers 422 and names it in missing_variables, before anything is charged or queued. The dashboard preview and test send show it empty instead.
• Values are HTML-escaped in the HTML body, so a value can never add markup to your email.
• Keys use letters, digits and underscores, up to 50 characters, and a template can declare up to 50. Types are string and number; a fallback must match its type.
• FIRST_NAME, LAST_NAME, EMAIL, UNSUBSCRIBE_URL, RESEND_UNSUBSCRIBE_URL, contact and this are reserved. The first three are contact fields: a broadcast fills them from the contact, and a transactional send fills them from the variables you pass under those names.
• {{{RESEND_UNSUBSCRIBE_URL}}} and {{unsubscribe_url}} become each recipient's own unsubscribe link.

Send with a template

Pass a template object to POST /v1/emails or to each item of POST /v1/emails/batch, with the template id or alias and the variables.

curl -X POST https://smtpfa.st/api/v1/emails \
  -H "Authorization: Bearer $SMTPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "template": {
      "id": "order-confirmation",
      "variables": { "PRODUCT": "Desk lamp", "PRICE": 49 }
    }
  }'

const res = await fetch("https://smtpfa.st/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMTPFAST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "[email protected]",
    template: { id: "order-confirmation", variables: { PRODUCT: "Desk lamp", PRICE: 49 } },
  }),
});
const { id } = await res.json();

• Only a published template can be sent. A template that was never published answers 422.
• Every variable that has no fallback and is used without an inline fallback needs a value. If one is missing, the send answers 422 with the keys in missing_variables.
• html, text and react cannot be sent together with a template.
• from, subject and reply_to in the request win over the template's defaults. A subject in the request is rendered with the same variables.
• After rendering, the email is an ordinary send: the sender domain must be verified, suppressed recipients are dropped, plan limits and credits apply, and an Idempotency-Key works as usual. A retry with the same key replays the first email, even if the template was published again since.

Start a broadcast from a template

Pass template_id when you create a broadcast, or choose Start from a template in the broadcast editor. The template's current content, as the template editor shows it, is copied into the new draft, and declared fallbacks are written into the tags so the broadcast renders the same. Any field you send alongside wins. A broadcast still needs an unsubscribe link before it can be sent.

POST /v1/broadcasts
{
  "template_id": "product-update",
  "name": "October update",
  "segment_id": "seg_customers"
}

Starter gallery

The Templates page in the dashboard has 10 starters you can copy in one click. They use table layout and inline styles, fit a 600px column, adapt to dark mode in the clients that support it, and need no external fonts or images.

Template object

{
  "object": "template",
  "id": "clx_tpl123",
  "current_version_id": "b2693018-7abb-4b4b-b4cb-aadf72dc06bd",
  "alias": "order-confirmation",
  "name": "Order confirmation",
  "status": "published",
  "published_at": "2026-10-03T09:12:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-03T09:12:00.000Z",
  "from": "Acme <[email protected]>",
  "subject": "Your order {{{ORDER_ID}}}",
  "reply_to": null,
  "html": "<p>Name: {{{PRODUCT}}}</p><p>Total: {{{PRICE}}}</p>",
  "text": null,
  "variables": [
    {
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "key": "PRODUCT",
      "type": "string",
      "fallback_value": "item",
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-01T08:00:00.000Z"
    }
  ],
  "has_unpublished_versions": false,
  "preview_text": null,
  "markdown": null,
  "category": "Billing"
}

The content fields are the draft. preview_text, markdown and category are SMTPfast additions.

Differences from Resend

• markdown, preview_text and category are extra fields, and the list accepts q.
• A text of exactly "" stops a text part being generated from the HTML, as in Resend, but the email still carries an empty plain-text alternative, as any SMTPfast email sent with text: "" does.
• Timestamps are ISO 8601.