Templates

Templates hold reusable content. You edit a draft and publish it; sends always render the published copy, so draft edits never affect live email until you publish again. Use a template from POST /v1/emails or from a broadcast. All template endpoints require a full_access key.

Variable syntax

Subject: Your order {{{ORDER_ID}}} has shipped

<p>Hi {{{first_name|there}}},</p>
<p>Track it here: <a href="{{{tracking_url}}}">{{{tracking_url}}}</a></p>

• {{{NAME}}} inserts a variable; {{{NAME|fallback}}} uses fallback when it is missing or empty. Double braces ({{name}}) work the same way.
• Names are matched case-insensitively.
• Values are always HTML-escaped in the HTML body (triple braces do not mean raw HTML), stripped of line breaks in the subject and inserted as-is in the text body. A value placed in a URL attribute (href, src, …) with a javascript:, vbscript: or data: scheme is replaced by #.
• A variable used without a fallback (inline or declared) must be supplied at send time, otherwise the send fails with 422 validation_error.

Create a template

# Create a template
curl -X POST 'https://api.bytesms.com/api/v1/templates' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Order shipped","alias":"order-shipped","subject":"Your order {{{order_id}}} has shipped","html":"<p>Hi {{{first_name|there}}}, order {{{order_id}}} is on its way.</p>","variables":[{"key":"first_name","type":"string"},{"key":"order_id","type":"number"}]}'

{
  "id": "cmg4n0q8d0005l8v9f2h6j3ks",
  "object": "template"
}

Retrieve a template

Top-level subject/html/text/variables are the draft; published is the live copy (null until first published).

# Retrieve a template
curl -X GET 'https://api.bytesms.com/api/v1/templates/order-shipped' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx'

{
  "object": "template",
  "id": "cmg4n0q8d0005l8v9f2h6j3ks",
  "name": "Order shipped",
  "alias": "order-shipped",
  "status": "published",
  "published_at": "2026-09-28T09:00:00.000Z",
  "from": null,
  "subject": "Your order {{{order_id}}} has shipped",
  "reply_to": null,
  "html": "<p>Hi {{{first_name|there}}}, order {{{order_id}}} is on its way.</p>",
  "text": null,
  "variables": [
    {
      "key": "first_name",
      "type": "string"
    },
    {
      "key": "order_id",
      "type": "number"
    }
  ],
  "has_unpublished_changes": false,
  "has_unpublished_versions": false,
  "published": {
    "subject": "Your order {{{order_id}}} has shipped",
    "html": "<p>Hi {{{first_name|there}}}, order {{{order_id}}} is on its way.</p>",
    "text": null,
    "variables": [
      {
        "key": "first_name",
        "type": "string"
      },
      {
        "key": "order_id",
        "type": "number"
      }
    ]
  },
  "created_at": "2026-09-28T08:45:00.000Z",
  "updated_at": "2026-09-28T09:00:00.000Z"
}

List templates

# List published templates
curl -X GET 'https://api.bytesms.com/api/v1/templates?status=published' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx'

Update a template

Updates the draft. Same fields as create, all optional; send null to clear an optional field (not name or variables). Returns { id, object: "template" }.

# Update the draft
curl -X PATCH 'https://api.bytesms.com/api/v1/templates/cmg4n0q8d0005l8v9f2h6j3ks' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"subject":"Shipped: order {{{order_id}}}"}'

Publish

Snapshots the current draft as the live version. The template needs an HTML or text body. Returns { id, object: "template" }.

Duplicate

Creates a copy named <name> (copy) and returns the new { id, object: "template" }.

Delete a template

{
  "object": "template",
  "id": "cmg4n0q8d0005l8v9f2h6j3ks",
  "deleted": true
}