Templates

A template is a reusable email — a subject and body authored with your company's brand — identified by a stable slug you send against.

Versions are immutable

Publishing a template creates an immutable version. Editing a published template doesn't change it in place; it creates a new draft version, which you publish in turn. This is what makes sends reproducible: a message records the version it rendered, and in-flight automations keep using the version they started with.

Only published templates can be sent. Sending an unpublished template returns 409 template_not_published.

Variables

Templates reference variables supplied as props at send time (e.g. {firstName}). Pass them on the send:

{ "template": "welcome", "to": "[email protected]", "props": { "firstName": "Jane" } }

Rendering

Templates are React Email components, rendered server-side to HTML and plain text. The render pipeline restricts what a template may import (only react and the email component library) and caches compiled output. The result is what your provider actually sends.

Localization

A template can carry translations — a published version per locale, added with POST /api/v1/templates/{slug}/translations. Each translation has its own subject and (optionally) its own body source.

At send time the locale is resolved in this order:

1. An explicit locale on the send ("fr", "pt-BR").
2. The contact's stored attributes.locale.
3. The base version.

A missing translation falls back to the base version rather than failing, so a partially translated template is safe to ship — untranslated locales keep receiving the base language.

Categories

A template is transactional or lifecycle. The distinction drives the suppression matrix and unsubscribe headers — lifecycle email carries one-click unsubscribe and is blocked for unsubscribed contacts; transactional email is not. See Suppression & unsubscribe.

A lifecycle template can additionally declare a topic, which scopes its unsubscribe to one stream instead of all lifecycle email — see Subscription topics.