Your plan: {{plan}}
", "plain_content": "Hi {{name}}. Your plan: {{plan}}.", "active": 1 }' ``` Fields: | Field | Type | Notes | |-------|------|-------| | `name` | string (required) | 1–255 chars; identifies the version | | `subject` | string | Template-rendered subject line (≤ 1000 chars) | | `preheader` | string | Preview text shown in the inbox list (≤ 500 chars); supports variables | | `html_content` | string | HTML body | | `plain_content` | string | Plain-text body (generated from HTML if omitted, but provide one — it's a deliverability signal) | | `editor` | string | UI editor type (typically `"design"` or `"code"`; informational) | | `active` | 0 or 1 | Set to `1` to immediately make this version the active one | Every new version defaults to `active: 0`. You can activate later with: ```bash curl -X POST https://scaisend.scailabs.ai/v3/templates/d-abc123/versions/v_xyz/activate \ -H "Authorization: Bearer $SCAISEND_API_KEY" ``` ## Sending with a template Once a version is active, send without `content`: ```bash curl -X POST https://scaisend.scailabs.ai/v3/mail/send \ -H "Authorization: Bearer $SCAISEND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "personalizations": [ { "to": [{"email": "ada@example.com"}], "dynamic_template_data": {"name": "Ada", "plan": "Pro"} } ], "from": {"email": "hello@mail.example.com"}, "template_id": "d-abc123" }' ``` `dynamic_template_data` becomes the context passed to the template engine. `{{name}}` in the template renders to `Ada`, `{{plan}}` to `Pro`. ## Template syntax ScaiSend uses [chevron](https://pypi.org/project/chevron/) under the hood — a Mustache implementation extended with Handlebars-style helpers. ### Variables ```handlebarsHi {{name}}
``` Output is HTML-escaped by default. To output raw HTML (dangerous; only use with trusted content): ```handlebarsThanks for being a subscriber!
{{else}} {{/if}} ``` ### Iteration ```handlebarsYour order of {{length order.items}} item{{#greaterThan (length order.items) 1}}s{{/greaterThan}}:
Total: ${{order.total}}
{{else}}Your order is empty.
{{/if}}— The {{uppercase company_name}} team
``` With data: ```json { "name": "Ada", "company_name": "Acme", "order": { "total": "42.99", "items": [ {"name": "Widget", "price": "12.99", "ship_date": "2026-04-25"}, {"name": "Gadget", "price": "29.99", "ship_date": "2026-04-26"} ] } } ``` Renders as: ```htmlYour order of 2 items:
Total: $42.99
— The ACME team
``` ## Preview text (preheader) The `preheader` field becomes the text shown next to the subject in the inbox list. Set it explicitly — otherwise email clients use the first ~100 chars of the body, which is often unhelpful. ```json { "name": "v1", "subject": "Your April receipt", "preheader": "Order #{{order_id}} — ${{order_total}}", "html_content": "..." } ``` Preheader supports variables. A typical pattern: use the preheader to summarize the CTA, since it's the first thing the recipient reads. ## Managing versions List versions of a template: ```bash curl https://scaisend.scailabs.ai/v3/templates/d-abc123/versions \ -H "Authorization: Bearer $SCAISEND_API_KEY" ``` Update a version (cannot modify an active version without deactivating first): ```bash curl -X PATCH https://scaisend.scailabs.ai/v3/templates/d-abc123/versions/v_xyz \ -H "Authorization: Bearer $SCAISEND_API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject": "New subject line", "html_content": "..."}' ``` Duplicate a version (useful for starting a new variant from the current active): ```bash curl -X POST https://scaisend.scailabs.ai/v3/templates/d-abc123/versions/v_xyz/duplicate \ -H "Authorization: Bearer $SCAISEND_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "v2-experiment-a"}' ``` The duplicate is inactive by default. Deactivate: ```bash curl -X POST https://scaisend.scailabs.ai/v3/templates/d-abc123/versions/v_xyz/deactivate \ -H "Authorization: Bearer $SCAISEND_API_KEY" ``` A template with no active version can't be used for sending — `/v3/mail/send` with that `template_id` returns 400. ## Rendering errors Template rendering happens in the Worker service, not the API. A rendering error (undefined variable accessed strictly, broken syntax, helper misuse) does not cause a 4xx on `/v3/mail/send`. Instead: - The message lands in `FAILED` status. - A `dropped` event is recorded with reason `template_render_error`. - The message's `error_message` field contains the rendering exception. Test your templates before relying on them. Send a test email with representative data via a test key — sandbox rendering catches the error the same way a real send would. ## Listing templates ```bash curl "https://scaisend.scailabs.ai/v3/templates?generation=dynamic" \ -H "Authorization: Bearer $SCAISEND_API_KEY" ``` Query parameters: | Parameter | Notes | |-----------|-------| | `generation` | `dynamic` or `legacy`; filter by template style | ## Deleting Deleting a template deletes all its versions. Active sends that reference the template mid-flight complete normally (they've already been snapshot-rendered). Future sends with the template_id return 400. ```bash curl -X DELETE https://scaisend.scailabs.ai/v3/templates/d-abc123 \ -H "Authorization: Bearer $SCAISEND_API_KEY" ``` Prefer deactivation (remove the active version) over deletion when you might want the template back. ## What's next - [Sending Mail](sending-mail) — using `template_id` on a send. - [Attachments and Images](attachments-and-images) — embedding images in templates. - [Templates Reference](../reference/templates) — exhaustive endpoint reference.