Templates and variables

Templates let you reuse email HTML and replace variables in the subject and body at send time. Customers can create, edit, and submit templates in the console, then reference approved and enabled templates through the API.

Create a template in the console

1. Open Email Templates and click New Template.
2. Choose Marketing or Transactional. The category cannot change after creation. Use marketing for promotions and transactional for verification codes, orders, and service notices.
3. Select the template language. Create a separate template for each required language; template.language in the API does not switch languages automatically.
4. Paste and preview content in the HTML editor. If AI Assistant is enabled for your account, you can generate or revise HTML with AI. Apply an AI proposal to the draft and save it before review; generation itself is not approval.
5. Save the draft and click Submit for Review. The platform reviews the current version. Later edits create a new version that must be reviewed again.

Review statuses

Copy the templateId from the list for API use. Before deleting a template, check that no campaign or business system uses it.

Variable syntax

Variables use double braces:

Hello {{firstName}}, your order {{orderNo}} has been confirmed.

• Names start with a letter and can then contain letters, digits, underscores, dots, and hyphens, up to 64 characters.
• A dot is part of the literal key: {{user.name}} reads the "user.name" key rather than automatically traversing a nested object.
• Only literal replacement is supported, not conditions, loops, or expressions.
• Both the subject and template body are rendered. Direct non-template text/html is not rendered.
• String and numeric values are recommended. Escape dynamic values appropriately for HTML to avoid broken layouts or unsafe markup.

For marketing unsubscribe links, use {{unsubscribe_url}} or the compatible shorthand {{unsubscribe}}. See Marketing email and unsubscribe.

Use a template through the API

{
  "from": {"email": "notify@example.com", "name": "Example"},
  "to": [{"email": "alice@example.net"}],
  "subject": "Order {{orderNo}} confirmed",
  "messageType": "TRANSACTIONAL",
  "variables": {
    "customerName": "Alice"
  },
  "template": {
    "templateId": "tpl_order_confirmation",
    "variables": {
      "orderNo": "ORDER-20261111-001"
    }
  }
}

• subject is required and can contain variables.
• Do not provide non-empty text/html together with template.
• Top-level variables provide common values; matching keys under template.variables take precedence.
• messageType must match the template purpose or the message can be rejected after acceptance.
• template.language is reserved and does not currently select a language. Omit it and use the templateId for the desired language.

Missing variables and outcomes

HTTP 202 only indicates acceptance. Disabled templates, unreviewed versions, missing variables, and type conflicts can fail later. Check Send records and statuses.

Common questions

Why did variables not change the body? Only template sending renders variables. Render a direct body in your own system first.

Why is an approved template still unable to send? Check that it is enabled, that it has not been edited since approval, and that its current and reviewed versions match.

Can I send direct content and a template together? No. Choose one mode.

Can I upload attachments through the API? There is no usable attachment upload or content-store capability, and attachment references do not produce actual attachment delivery.

Related resources