Create a new template

Creates a new message template with header, body, footer, and buttons. The template can be submitted for review immediately or saved as draft for later submission. There is no name field on create — the display name is derived from the template's content and can be changed afterwards with PUT /v3/templates/{id}.

POST
/v3/templates

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v3/templates" \  -H "Idempotency-Key: req_abc123_retry1" \  -H "Content-Type: application/json" \  -d '{    "category": "MARKETING",    "language": "en_US",    "definition": {      "body": {        "multiChannel": {          "type": "text",          "template": "Hello {{0:variable}}! Welcome to {{1:variable}}. We are glad to have you on board.",          "variables": [            {              "id": 0,              "name": "name",              "type": "variable",              "props": {                "variableType": "text",                "sample": "John"              }            },            {              "id": 1,              "name": "company",              "type": "variable",              "props": {                "variableType": "text",                "sample": "SentDM"              }            }          ]        }      },      "definitionVersion": "1.0"    },    "auto_create_for_sp": false,    "submit_for_review": false,    "sandbox": false  }'
{
  "success": true,
  "data": {
    "id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Welcome Message",
    "category": "MARKETING",
    "auto_reply_action": null,
    "language": "en_US",
    "status": "DRAFT",
    "channels": [
      "sms",
      "whatsapp",
      "rcs"
    ],
    "variables": [
      "name",
      "company"
    ],
    "created_at": "2026-11-01T16:39:13.8694469+00:00",
    "updated_at": "2026-11-01T16:39:13.8694549+00:00",
    "is_published": false
  },
  "error": null,
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-11-01T16:39:13.8694732+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_004",
    "message": "A required field is missing",
    "details": {
      "definition": [
        "Template definition is required"
      ]
    },
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-11-01T16:39:13.8694785+00:00",
    "version": "v3"
  }
}
Empty
Empty
{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_001",
    "message": "Failed to create template",
    "details": null,
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-11-01T16:39:13.8694791+00:00",
    "version": "v3"
  }
}

Get template by ID GET

Retrieves a specific template by its ID. Returns template details including name, category, language, status, and definition.

Update a template PUT

Updates an existing template's name, category, language, definition, or submits it for review. While the template is in review (status PENDING, or any channel awaiting a verdict) its definition, category and language are frozen and a resubmission is refused — those requests answer 409 CONFLICT_006. The display name stays editable throughout. `definition`, `category` and `language` are editable only from status DRAFT, REJECTED or APPROVED. An edit to any of them on a template in another state (PAUSED, DISABLED or REVOKED) is refused with 400 VALIDATION_001 and the detail "Template (except display name) cannot be updated unless it is in draft or rejected status"; `name` stays editable in every state. `submit_for_review` on a PAUSED, DISABLED or REVOKED template is accepted and answers 200, but opens no review and does not move the status — only the reviewer can reinstate it. Editing an APPROVED template is a live edit: the new content is stored immediately, and sending `submit_for_review: true` re-opens review, which returns the affected channels to PENDING so they stop sending until they are approved again. The previously approved content is never sent during re-review. Watch the per-channel `templates` webhook events rather than assuming the template-level status. Templates provisioned by Sent (light-onboarding templates, whose names carry the reserved `sent_` prefix) are read-only: every field is refused with 400 VALIDATION_001 and the detail "This template is read-only. Only 'submit for review' is allowed.", and only `submit_for_review` is accepted. A `name` starting with `sent_` is refused for the same reason — the prefix is reserved.