Message Templates

Message Templates are reusable SMS and email content records for Chimes. Use them when customer communication needs draft review, publishing, variable validation, and channel safety checks before delivery. Chime sends, schedules, and broadcasts render the published version; render previews can inspect the current draft before you publish it.

The Message Template object

A Message Template stores one channel of content. SMS templates use sms.message_template; email templates use email.subject and email.html. Do not mix SMS and email content in the same template.

Properties

Name
about
Type
string|null
Description
Optional internal description of the template's purpose.
Name
archived_at
Type
timestamp|null
Description
When the template was archived. Archived templates cannot be updated, published, rendered, or used for new Chimes.
Name
attachments
Type
array
Description
Up to 25 email attachment file IDs. Every entry must be nonempty and match file_ followed by alphanumeric characters. Attachments are accepted only for email templates, but Chimes do not deliver rendered template attachments yet.
Name
channel
Type
enum
Description
Template channel: sms or email.
Name
created_at
Type
timestamp
Description
When the template was created.
Name
draft_version
Type
integer
Description
Current draft version. The first edit after publication advances this number; later edits replace that same draft until it is published.
emailobjectEmail template content. Present when channel is email.Click or tap to expand
- Name
  from
  Type
  object|null
  Description
  Optional sender mailbox template.
- Name
  headers
  Type
  object
  Description
  Optional provider-neutral header templates.
- Name
  html
  Type
  string
  Description
  HTML template body. Required for email templates.
- Name
  reply_to
  Type
  object|null
  Description
  Optional reply-to mailbox template.
- Name
  subject
  Type
  string
  Description
  Email subject template. Required for email templates.
Name
has_unpublished_changes
Type
boolean
Description
true when the draft differs from the published version.
Name
id
Type
string
Description
Generated template ID. The API assigns this value; clients must not provide id, template_id, or a custom key on create.
Name
locale
Type
string
Description
Locale for the template. Defaults to en when omitted.
Name
name
Type
string
Description
Human-readable template name.
Name
published_at
Type
timestamp|null
Description
When the current published version was published.
Name
published_version
Type
integer|null
Description
Version number currently used by Chime sends. null until the template is published.
Name
purpose
Type
string
Description
Template category, such as receipt, shipping_update, marketing, or reminder.
smsobjectSMS template content. Present when channel is sms.Click or tap to expand
- Name
  message_template
  Type
  string
  Description
  SMS body template. Required for SMS templates.
Name
status
Type
enum
Description
Current lifecycle state: draft, published, or archived.
Name
updated_at
Type
timestamp
Description
When the template was last changed.
variablesobjectVariable declarations available inside template content.Click or tap to expand
- Name
  about
  Type
  string
  Description
  Optional description shown to operators.
- Name
  default
  Type
  any
  Description
  Default value used when an optional variable is omitted.
- Name
  items
  Type
  array
  Description
  Nested item fields for array variables. Nested arrays are not supported.
- Name
  name
  Type
  string
  Description
  Variable name. Must start with a lowercase letter and contain lowercase letters, numbers, or underscores.
- Name
  required
  Type
  boolean
  Description
  Whether callers must provide this variable when rendering.
- Name
  type
  Type
  enum
  Description
  array, boolean, date, datetime, email, integer, number, phone, string, or url.
Name
version
Type
integer
Description
Current template version number.

Template expressions use {{variable_name}} for values, {{#if variable}}...{{else}}...{{/if}} for conditional text, and {{#each items as item}}...{{/each}} for arrays. Values are validated and escaped for the target channel during rendering. URL variables must render to HTTP or HTTPS URLs.

Create a message template

Create a reusable SMS or email template. The new template starts as draft; publish it before using it in Chime sends, schedules, or broadcasts.

Request body

Name
about
Type
string
Description
Optional internal description.
Name
attachments
Type
array
Description
Up to 25 email attachment file IDs. Only allowed when channel is email. Every entry must be nonempty and match file_ followed by alphanumeric characters, such as file_ABC123.
Name
channel
Type
enum
Description
sms or email.
Name
email
Type
object
Description
Required when channel is email. Must include subject and html; may include from, reply_to, and headers.
Name
locale
Type
string
Description
Optional locale. Defaults to en.
Name
name
Type
string
Description
Human-readable template name.
Name
purpose
Type
string
Description
Template category for filtering and analytics.
Name
sms
Type
object
Description
Required when channel is sms. Must include message_template.
Name
variables
Type
array
Description
Variable declarations used by the SMS body, email subject, HTML, sender, reply-to, and headers.

Response

Returns a top-level message_template object. Store message_template.id; it is the value Chime requests use as message_template.template_id.

Request

POST

/message_templates/create

curl https://api.zebo.dev/message_templates/create \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Idempotency-Key: mtpl-create-shipping-sms-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shipping update SMS",
    "channel": "sms",
    "purpose": "shipping_update",
    "variables": [
      { "name": "customer_name", "type": "string", "required": true },
      { "name": "tracking_url", "type": "url", "required": true }
    ],
    "sms": {
      "message_template": "Hi {{customer_name}}, your order shipped. Track it: {{tracking_url}}"
    }
  }'

Response

{
  "message_template": {
    "id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
    "name": "Shipping update SMS",
    "channel": "sms",
    "purpose": "shipping_update",
    "locale": "en",
    "status": "draft",
    "version": 1,
    "draft_version": 1,
    "has_unpublished_changes": true,
    "variables": [
      { "name": "customer_name", "type": "string", "required": true },
      { "name": "tracking_url", "type": "url", "required": true }
    ],
    "sms": {
      "message_template": "Hi {{customer_name}}, your order shipped. Track it: {{tracking_url}}"
    },
    "created_at": "2026-06-22T10:30:00Z",
    "updated_at": "2026-06-22T10:30:00Z"
  }
}

Update a message template

Update mutable fields by replacing the current draft. The first edit after publication advances the draft version; later edits keep that same draft version until it is published. The published version remains stable until you publish the draft.

Request body

Name
about
Type
string
Description
Optional replacement description.
Name
attachments
Type
array
Description
Up to 25 replacement email attachment file IDs. Only allowed for email templates. Every entry must be nonempty and match file_ followed by alphanumeric characters, such as file_ABC123.
Name
channel
Type
enum
Description
Optional channel assertion. Existing templates cannot move between sms and email; create a new template for a different channel.
Name
email
Type
object
Description
Replacement email content.
Name
id
Type
string
Description
Template ID to update.
Name
locale
Type
string
Description
Replacement locale.
Name
name
Type
string
Description
Replacement name.
Name
purpose
Type
string
Description
Replacement purpose.
Name
sms
Type
object
Description
Replacement SMS content.
Name
variables
Type
array
Description
Replacement variable declarations.

Response

Returns the updated message_template with has_unpublished_changes: true.

Request

POST

/message_templates/update

curl https://api.zebo.dev/message_templates/update \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Idempotency-Key: mtpl-update-shipping-sms-001" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
    "sms": {
      "message_template": "Hi {{customer_name}}, your order shipped. Track: {{tracking_url}}"
    }
  }'

Publish a message template

Publish the current draft version. Chime sends, schedules, and broadcasts render only the published version.

Request body

Name
id
Type
string
Description
Template ID to publish.

Response

Returns the published message_template with status: "published" and has_unpublished_changes: false.

Request

POST

/message_templates/publish

curl https://api.zebo.dev/message_templates/publish \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Idempotency-Key: mtpl-publish-shipping-sms-001" \
  -H "Content-Type: application/json" \
  -d '{ "id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU" }'

Archive a message template

Archive a template so it cannot be updated, published, rendered, or used for new Chime sends. Archiving preserves the historical record and existing Chimes.

Request body

Name
id
Type
string
Description
Template ID to archive.

Response

Returns the archived message_template.

Request

POST

/message_templates/archive

curl https://api.zebo.dev/message_templates/archive \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Idempotency-Key: mtpl-archive-shipping-sms-001" \
  -H "Content-Type: application/json" \
  -d '{ "id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU" }'

Look up a message template

Retrieve one template by ID. Use lookup before editing, publishing, or showing a template detail view in your dashboard.

Request body

Name
id
Type
string
Description
Template ID to retrieve.

Response

Returns the matching message_template.

Request

POST

/message_templates/lookup

curl https://api.zebo.dev/message_templates/lookup \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU" }'

Page message templates

Retrieve a page of templates for the authenticated application. Filter by channel, locale, purpose, or status when you are building an operator dashboard.

Request body

Name
channel
Type
enum
Description
Filter by sms or email.
Name
locale
Type
string
Description
Filter by locale.
Name
page
Type
integer
Description
1-based page number. Defaults to 1 when omitted or nonpositive.
Name
purpose
Type
string
Description
Filter by purpose.
Name
size
Type
integer
Description
Requested page capacity. Defaults to 25 when omitted or nonpositive.
Name
status
Type
enum
Description
Filter by draft, published, or archived.

Response

Returns a top-level page object. number is the page number, message_templates contains the returned records, and response size is the number of records actually returned rather than the requested capacity.

Request

POST

/message_templates/page

curl https://api.zebo.dev/message_templates/page \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page": 1, "size": 25, "channel": "sms", "status": "published" }'

Response

{
  "page": {
    "number": 1,
    "size": 1,
    "message_templates": [
      {
        "id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
        "name": "Shipping update SMS",
        "channel": "sms",
        "purpose": "shipping_update",
        "locale": "en",
        "status": "published",
        "version": 1,
        "published_version": 1,
        "draft_version": 1,
        "has_unpublished_changes": false
      }
    ]
  }
}

Render a message template preview

Render a template with variables before sending. Preview rendering is draft-aware, so operators can check unpublished changes before publishing. Chime send, schedule, and broadcast requests still require a published version.

Request body

message_templateobjectRequired. Template reference and render variables.Click or tap to expand
- Name
  template_id
  Type
  string
  Description
  Required. Template ID to render.
- Name
  variables
  Type
  object
  Description
  Values for the declared template variables.

Response

Returns the template record plus rendered channel content. SMS previews return rendered.sms.full_message; email previews return rendered email fields.

Request

POST

/message_templates/render_preview

curl https://api.zebo.dev/message_templates/render_preview \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_template": {
      "template_id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
      "variables": {
        "customer_name": "Gloria",
        "tracking_url": "https://track.example.com/OR-12345"
      }
    }
  }'

Response

{
  "message_template": {
    "id": "mtpl_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
    "name": "Shipping update SMS",
    "channel": "sms",
    "status": "published",
    "published_version": 1,
    "draft_version": 1
  },
  "rendered": {
    "channel": "sms",
    "sms": {
      "full_message": "Hi Gloria, your order shipped. Track it: https://track.example.com/OR-12345"
    }
  }
}

Send Chime - Send one notification with an inline or stored template.
Schedule Chime - Schedule notifications with stored template rendering.
Broadcast Chimes - Send one rendered template to a same-channel audience.