> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/templates.md).

# Templates

Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications.

## List available merge tags for the account/workroom.

> Catalog for writing template bodies. Returns the three-source union the dashboard's email editor uses — Workroom Attributes (per-workroom contact fields), Special Attributes / Managed Links (\`{label}\` - email also accepts \`\[label]\` - + \`{unsubscribe\_url}\`), and Static Attributes (visits/purchases/appointments/workroom-info + \`mergetagstaticattributes\` catalog).\
> \
> Also returns canonical \`syntax\` examples (single-brace, pipe defaults) and a \`dont\` list of common mistakes (Liquid double-brace, \`contact.\` namespace, invented tags). Use to avoid empty-render failures — a tag that doesn't resolve renders as empty string with no error.\
> \
> Workroom-aware via \`?workroom=\<name-or-id>\` or the \`Gleantap-Workroom\` header. Without a scope, workroom attributes union across the account.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"MergeTagCatalog":{"type":"object","description":"Merge-tag catalog for the current account/workroom. Combines the same three sources the dashboard's email template editor uses. Use this to pick real field names when constructing template bodies — a merge tag that doesn't resolve renders as an empty string, so guessing is silent failure.\n","properties":{"object":{"type":"string","enum":["merge_tag_catalog"]},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true},"categories":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","enum":["workroom","special","static"]},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"object","required":["value","syntax"],"properties":{"value":{"type":"string","description":"The field key."},"syntax":{"type":"string","description":"Copy-paste form — either `{value}` or (for managed links) `[value]`."},"label":{"type":"string","description":"Human-readable label."},"data_type":{"type":"string","nullable":true,"description":"Where known (workroom category only)."},"target":{"type":"string","nullable":true,"description":"Only for managed short-links — the destination URL."}}}}}}},"syntax":{"type":"object","properties":{"format":{"type":"string","enum":["single-brace"]},"defaults":{"type":"string"},"dont":{"type":"array","items":{"type":"string"}}}},"notes":{"type":"array","items":{"type":"string"}}}},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"}}},"paths":{"/templates/merge_tags":{"get":{"tags":["Templates"],"operationId":"describeMergeTags","summary":"List available merge tags for the account/workroom.","description":"Catalog for writing template bodies. Returns the three-source union the dashboard's email editor uses — Workroom Attributes (per-workroom contact fields), Special Attributes / Managed Links (`{label}` - email also accepts `[label]` - + `{unsubscribe_url}`), and Static Attributes (visits/purchases/appointments/workroom-info + `mergetagstaticattributes` catalog).\n\nAlso returns canonical `syntax` examples (single-brace, pipe defaults) and a `dont` list of common mistakes (Liquid double-brace, `contact.` namespace, invented tags). Use to avoid empty-render failures — a tag that doesn't resolve renders as empty string with no error.\n\nWorkroom-aware via `?workroom=<name-or-id>` or the `Gleantap-Workroom` header. Without a scope, workroom attributes union across the account.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"filter","in":"query","description":"Case-insensitive substring match against a tag's value or label, across all three categories.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Narrow to one category instead of all three.","schema":{"type":"string","enum":["workroom","special","static"]}},{"name":"limit","in":"query","description":"Cap on the Workroom Attributes group specifically (default 100, max 500). The special/static groups are always returned in full.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"The merge tag catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeTagCatalog"}}}}}}}}}
```

## List template folders.

> Backed by the dashboard's \`tags\` collection, filtered to campaign\_type='template'.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"TemplateFolder":{"type":"object","properties":{"object":{"type":"string","const":"template_folder"},"id":{"$ref":"#/components/schemas/TemplateFolderId"},"name":{"type":"string"},"template_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time","nullable":true}}},"TemplateFolderId":{"type":"string","pattern":"^tfd_[0-9a-fA-F]{24}$","description":"Template folder ID."}}},"paths":{"/templates/folders":{"get":{"tags":["Templates"],"operationId":"listTemplateFolders","summary":"List template folders.","description":"Backed by the dashboard's `tags` collection, filtered to campaign_type='template'.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"}],"responses":{"200":{"description":"A page of folders.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateFolder"}}}}]}}}}}}}}}
```

## Create a template folder.

> Names must be unique within a workroom; conflicts return 409.\
> \
> Requires the folder name. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"TemplateFolderCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1}}},"TemplateFolder":{"type":"object","properties":{"object":{"type":"string","const":"template_folder"},"id":{"$ref":"#/components/schemas/TemplateFolderId"},"name":{"type":"string"},"template_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time","nullable":true}}},"TemplateFolderId":{"type":"string","pattern":"^tfd_[0-9a-fA-F]{24}$","description":"Template folder ID."}}},"paths":{"/templates/folders":{"post":{"tags":["Templates"],"operationId":"createTemplateFolder","summary":"Create a template folder.","description":"Names must be unique within a workroom; conflicts return 409.\n\nRequires the folder name. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateFolderCreate"}}}},"responses":{"201":{"description":"Folder created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateFolder"}}}},"409":{"description":"Name conflict."}}}}}}
```

## GET /templates/folders/{id}

> Retrieve a template folder.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"TemplateFolder":{"type":"object","properties":{"object":{"type":"string","const":"template_folder"},"id":{"$ref":"#/components/schemas/TemplateFolderId"},"name":{"type":"string"},"template_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time","nullable":true}}},"TemplateFolderId":{"type":"string","pattern":"^tfd_[0-9a-fA-F]{24}$","description":"Template folder ID."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/folders/{id}":{"get":{"tags":["Templates"],"operationId":"retrieveTemplateFolder","summary":"Retrieve a template folder.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateFolder"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## PATCH /templates/folders/{id}

> Rename a template folder.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"TemplateFolderUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1}}},"TemplateFolder":{"type":"object","properties":{"object":{"type":"string","const":"template_folder"},"id":{"$ref":"#/components/schemas/TemplateFolderId"},"name":{"type":"string"},"template_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time","nullable":true}}},"TemplateFolderId":{"type":"string","pattern":"^tfd_[0-9a-fA-F]{24}$","description":"Template folder ID."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/folders/{id}":{"patch":{"tags":["Templates"],"operationId":"updateTemplateFolder","summary":"Rename a template folder.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateFolderUpdate"}}}},"responses":{"200":{"description":"Updated folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateFolder"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Name conflict."}}}}}}
```

## Delete a template folder.

> Templates in the folder become unfoldered (they are not deleted).\
> \
> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/templates/folders/{id}":{"delete":{"tags":["Templates"],"operationId":"deleteTemplateFolder","summary":"Delete a template folder.","description":"Templates in the folder become unfoldered (they are not deleted).\n\n**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## List templates.

> Paginated list. Common filters: \`?filter\[channel]=email\`, \`?filter\[status]=published\`, \`?filter\[name]=welcome\` (case-insensitive prefix), \`?filter\[tags]=onboarding\`. Rate limit bucket: \`read\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}},"SortParam":{"name":"sort","in":"query","required":false,"description":"Comma-separated list of fields to sort by. Leading `-` reverses. Default `-created_at`. Sortable fields vary per resource; unsortable fields return 400 `invalid_sort_field`.\n","schema":{"type":"string"}},"FieldsParam":{"name":"fields","in":"query","required":false,"description":"Sparse fieldset — comma-separated list of fields to include in the response. Reduces payload size on high-volume reads. Nested field access is not supported; request the parent object.\n","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Template":{"type":"object","description":"Reusable message body. Channel-specific content fields (email uses `body_html`/`body_text`; SMS uses `body`; voice uses `script` + `voice_id`). Unused fields are null. `subject` is read-only/legacy - see its own description.\n","required":["id","object","name","channel","status","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/TemplateId"},"object":{"type":"string","const":"template"},"name":{"type":"string","maxLength":200},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"status":{"$ref":"#/components/schemas/TemplateStatus"},"version":{"type":"integer","description":"The template's current (live) version number. Bumped by every save, from the API or the dashboard."},"published_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate published version)."},"draft_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate draft)."},"subject":{"type":"string","nullable":true,"description":"Read-only legacy field - not settable via create/update. Templates have no subject line in the dashboard (that's a campaign-level concept); any value here is leftover from before that was enforced. Will be null on every template going forward."},"body_html":{"type":"string","nullable":true,"description":"Email only."},"body_text":{"type":"string","nullable":true,"description":"Email only. Recommended even when `body_html` is set."},"body":{"type":"string","nullable":true,"description":"SMS only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded."},"script":{"type":"string","nullable":true,"description":"Voice only. TTS script."},"voice_id":{"type":"string","nullable":true,"description":"Voice only. Provider-specific identifier. There is no default voice - required whenever `script` is set, and required before publish."},"from":{"$ref":"#/components/schemas/EmailAddress","nullable":true,"description":"Email only. Default sender."},"reply_to":{"$ref":"#/components/schemas/Email","nullable":true},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels (not contact tags)."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"TemplateChannel":{"type":"string","enum":["email","sms","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"TemplateStatus":{"type":"string","enum":["active","archived"],"description":"Templates have no draft/publish lifecycle - same as the dashboard, every saved template is live: create and PATCH take effect immediately for the dashboard, campaigns, flows and sends. `active` — every live template (email templates are stored exactly as the dashboard's Save writes them: `status: \"active\"`, `drafted: false`). `archived` — only templates flag-archived by an older API version (`DELETE` now really deletes); resolvable with `?include_archived=true`. Earlier API versions returned `draft` / `published`; both now read as `active`, and `filter[status]=draft|published|active` all list every live template.\n"},"EmailAddress":{"type":"object","required":["email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"}}},"Email":{"type":"string","format":"email"},"TemplateVariable":{"type":"object","required":["name","type"],"description":"Declared variable for the template. Variables are Liquid-interpolated at render time. Undeclared variables are still substituted if passed, but declared variables get validation + default handling.\n","properties":{"name":{"type":"string","description":"Variable name in Liquid form, e.g. `contact.first_name`, `booking_time`.","pattern":"^[a-zA-Z_][a-zA-Z0-9_.]*$"},"type":{"$ref":"#/components/schemas/TemplateVariableType"},"required":{"type":"boolean","default":false},"default":{"type":["string","number","boolean","null"],"description":"Fallback value if the variable is not provided at render time. Its type should match the variable's declared `type`."},"description":{"type":"string","maxLength":500}}},"TemplateVariableType":{"type":"string","enum":["string","number","boolean","date","url"]},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates":{"get":{"tags":["Templates"],"operationId":"listTemplates","summary":"List templates.","description":"Paginated list. Common filters: `?filter[channel]=email`, `?filter[status]=published`, `?filter[name]=welcome` (case-insensitive prefix), `?filter[tags]=onboarding`. Rate limit bucket: `read`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"$ref":"#/components/parameters/SortParam"},{"$ref":"#/components/parameters/FieldsParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"A page of templates.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Create a template.

> Creates a new template. Like a template saved in the dashboard it is live immediately - selectable in the dashboard, campaigns, flows and the Inbox, with no publish step. \`channel\` is immutable after creation.\
> \
> If the user wants this in a folder, call \`GET /v3/templates/folders\` first and let them choose from the existing list (or confirm a new one) rather than guessing a folder name.\
> \
> \# Merge-tag format (Gleantap standard)\
> \
> Use \*\*single braces\*\* (\`{ }\`), a \*\*flat field name\*\* (no \`contact.\` prefix), and a \*\*pipe\*\* for defaults. This matches the legacy \`Cron.php::format\_field\` interpolator that renders every send.\
> \
> \- Correct:   \`Hi {first\_name|there},\`\
> \- Correct:   \`Your city is {data.city}\`\
> \- Correct:   \`Membership status: {memberships.status|inactive}\`\
> \- Correct:   \`Class on {class\_date|format="M d, Y"}\`    (date format directive - PHP \`date()\` letters; dates render in the account timezone)\
> \- Correct:   \`Book here: {booking\_link}\`              (a workroom managed link, by its label)\
> \- Wrong:     \`Hi {{contact.first\_name}}, ...\`         (double brace — this is Liquid, not Gleantap)\
> \- Wrong:     \`Hi {{ first\_name | default: "there" }}\` (Liquid filters not supported)\
> \- Wrong:     \`{contact.first\_name}\`                   (no \`contact.\` namespace)\
> \- Wrong:     \`{cta\_url}\` or \`{promo\_code}\` or \`{deadline}\` if those aren't real contact fields — the tag renders as empty.\
> \
> \# Available fields\
> \
> \*\*Always available on a contact:\*\* \`first\_name\`, \`last\_name\`, \`email\`, \`phone\`, \`dob\`.\
> \
> \*\*Under \`data.\<key>\`:\*\* everything in \`Custom Fields\` (\`GET /v3/custom\_fields\`). E.g. \`{data.favorite\_color}\`, \`{data.company}\`.\
> \
> \*\*Structured domain data (dot-path into an array's first element):\*\*\
> &#x20; \- \`{memberships.status}\`, \`{memberships.type}\`, \`{memberships.renewal\_date}\`, \`{memberships.next\_billing\_date}\`, \`{memberships.price}\`, \`{memberships.sessions\_remaining}\`\
> &#x20; \- \`{purchases.last\_amount}\`, \`{purchases.all\_products\_purchased}\`\
> \
> \*\*Discover the full catalog\*\* by calling \`GET /v3/templates/merge\_tags\` (MCP: \`describeMergeTags\`). Returns three categories — Workroom Attributes (per-workroom contact fields), Special Attributes / Managed Links (short-link labels + \`{unsubscribe\_url}\`), and Static Attributes (visits/purchases/appointments/workroom-info) — plus syntax examples and gotchas. Optional: \`GET /v3/segments/schema\` (\`describeSegmentSchema\`) has richer type/values info for segment-DSL fields, but for template merge tags prefer \`describeMergeTags\`.\
> \
> A tag that doesn't resolve renders as the empty string with no error. If you need a runtime placeholder (\`{cta\_url}\`, \`{promo\_code}\`, \`{deadline}\`), pass it through the campaign or notification \`variables\` object at send-time — the interpolator checks \`variables\` before contact fields.\
> \
> \# Content shape by channel\
> \
> \- \*\*\`sms\`\*\* — \`body\` (plain text, at most 10 segments: 1530 GSM characters, or 670 with emoji/other non-GSM characters; merge tags count as written. Keep merge-tag budget under 30 total chars vs. carrier segment cost).\
> \- \*\*\`email\`\*\* — \`subject\` + \`body\_html\` (and optional \`body\_text\` for plain-text alternative). Subject supports merge tags too. Use inline CSS; external stylesheets get stripped by many email clients.\
> \- \*\*\`voice\`\*\* — \`script\` (SSML or plain text) + \`voice\_id\`.\
> \
> Requires the channel, subject and body content. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\
> \
> \*\*Names are not unique.\*\* \`name\` has no uniqueness constraint — two templates (even the same channel, even the same account) can share the exact same name. Template names are not unique: creating one with an existing name succeeds, after which that name no longer identifies a single template.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (≤255 chars) chosen by the client. Replays with the same key + same body return the cached response. Replays with the same key + different body return 409 `idempotency_conflict`. Required on messaging sends and bulk operations; recommended elsewhere.\n","schema":{"type":"string","maxLength":255}}},"schemas":{"TemplateCreate":{"type":"object","required":["name","channel"],"description":"Create a template (live immediately - there is no draft state). Provide channel-appropriate content (email: `body_html`/`body_text`; sms: `body`; voice: `script` + `voice_id`). Content can also be set later via `PATCH`. A content field for a DIFFERENT channel than the one being created (e.g. `body` on a `voice` template) is rejected with a 422 naming the correct field - it is never silently dropped.\n\nTemplates have no `subject` field, on any channel - the dashboard's template editor has no subject-line input at all (that's a campaign-level concept, not a template one). Sending `subject` is rejected with a 422, not silently dropped. A template's subject is chosen when it's used inside a campaign.\n\nA content field that's present but whitespace-only (e.g. `body: \"   \"`) is rejected with a 422 - omit the field instead to create an intentional empty stub.\n\nVoice templates: `voice_id` is required whenever `script` is set - there is no default voice, so a voice template without one can never actually be used to place a call.\n","properties":{"name":{"type":"string","maxLength":200},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"body_html":{"type":"string"},"body_text":{"type":"string"},"body":{"type":"string","maxLength":1530,"description":"SMS templates only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long`."},"script":{"type":"string"},"voice_id":{"type":"string","description":"Required whenever `script` is set, and required before publish - there is no default voice."},"from":{"$ref":"#/components/schemas/EmailAddress"},"reply_to":{"$ref":"#/components/schemas/Email"},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels. Prefer `folder_id` to place the template in a folder. If `folder_id` is omitted, the FIRST entry here is also resolved as a folder (id or name, find-or-create) - same fallback as `folder_id`, for callers that can only send `tags`."},"locale":{"$ref":"#/components/schemas/Locale"},"metadata":{"$ref":"#/components/schemas/Metadata"},"folder_id":{"type":"string","description":"The template folder to create this template in, by id (tfd_...) or by name. An unrecognized name auto-creates a new folder - call GET /v3/templates/folders first and let the user choose from the existing list (or confirm a new one) instead of guessing a name. Omit to leave it unfoldered. Takes priority over any folder inferred from `tags[0]`."}}},"TemplateChannel":{"type":"string","enum":["email","sms","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"EmailAddress":{"type":"object","required":["email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"}}},"Email":{"type":"string","format":"email"},"TemplateVariable":{"type":"object","required":["name","type"],"description":"Declared variable for the template. Variables are Liquid-interpolated at render time. Undeclared variables are still substituted if passed, but declared variables get validation + default handling.\n","properties":{"name":{"type":"string","description":"Variable name in Liquid form, e.g. `contact.first_name`, `booking_time`.","pattern":"^[a-zA-Z_][a-zA-Z0-9_.]*$"},"type":{"$ref":"#/components/schemas/TemplateVariableType"},"required":{"type":"boolean","default":false},"default":{"type":["string","number","boolean","null"],"description":"Fallback value if the variable is not provided at render time. Its type should match the variable's declared `type`."},"description":{"type":"string","maxLength":500}}},"TemplateVariableType":{"type":"string","enum":["string","number","boolean","date","url"]},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Template":{"type":"object","description":"Reusable message body. Channel-specific content fields (email uses `body_html`/`body_text`; SMS uses `body`; voice uses `script` + `voice_id`). Unused fields are null. `subject` is read-only/legacy - see its own description.\n","required":["id","object","name","channel","status","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/TemplateId"},"object":{"type":"string","const":"template"},"name":{"type":"string","maxLength":200},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"status":{"$ref":"#/components/schemas/TemplateStatus"},"version":{"type":"integer","description":"The template's current (live) version number. Bumped by every save, from the API or the dashboard."},"published_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate published version)."},"draft_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate draft)."},"subject":{"type":"string","nullable":true,"description":"Read-only legacy field - not settable via create/update. Templates have no subject line in the dashboard (that's a campaign-level concept); any value here is leftover from before that was enforced. Will be null on every template going forward."},"body_html":{"type":"string","nullable":true,"description":"Email only."},"body_text":{"type":"string","nullable":true,"description":"Email only. Recommended even when `body_html` is set."},"body":{"type":"string","nullable":true,"description":"SMS only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded."},"script":{"type":"string","nullable":true,"description":"Voice only. TTS script."},"voice_id":{"type":"string","nullable":true,"description":"Voice only. Provider-specific identifier. There is no default voice - required whenever `script` is set, and required before publish."},"from":{"$ref":"#/components/schemas/EmailAddress","nullable":true,"description":"Email only. Default sender."},"reply_to":{"$ref":"#/components/schemas/Email","nullable":true},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels (not contact tags)."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"TemplateStatus":{"type":"string","enum":["active","archived"],"description":"Templates have no draft/publish lifecycle - same as the dashboard, every saved template is live: create and PATCH take effect immediately for the dashboard, campaigns, flows and sends. `active` — every live template (email templates are stored exactly as the dashboard's Save writes them: `status: \"active\"`, `drafted: false`). `archived` — only templates flag-archived by an older API version (`DELETE` now really deletes); resolvable with `?include_archived=true`. Earlier API versions returned `draft` / `published`; both now read as `active`, and `filter[status]=draft|published|active` all list every live template.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates":{"post":{"tags":["Templates"],"operationId":"createTemplate","summary":"Create a template.","description":"Creates a new template. Like a template saved in the dashboard it is live immediately - selectable in the dashboard, campaigns, flows and the Inbox, with no publish step. `channel` is immutable after creation.\n\nIf the user wants this in a folder, call `GET /v3/templates/folders` first and let them choose from the existing list (or confirm a new one) rather than guessing a folder name.\n\n# Merge-tag format (Gleantap standard)\n\nUse **single braces** (`{ }`), a **flat field name** (no `contact.` prefix), and a **pipe** for defaults. This matches the legacy `Cron.php::format_field` interpolator that renders every send.\n\n- Correct:   `Hi {first_name|there},`\n- Correct:   `Your city is {data.city}`\n- Correct:   `Membership status: {memberships.status|inactive}`\n- Correct:   `Class on {class_date|format=\"M d, Y\"}`    (date format directive - PHP `date()` letters; dates render in the account timezone)\n- Correct:   `Book here: {booking_link}`              (a workroom managed link, by its label)\n- Wrong:     `Hi {{contact.first_name}}, ...`         (double brace — this is Liquid, not Gleantap)\n- Wrong:     `Hi {{ first_name | default: \"there\" }}` (Liquid filters not supported)\n- Wrong:     `{contact.first_name}`                   (no `contact.` namespace)\n- Wrong:     `{cta_url}` or `{promo_code}` or `{deadline}` if those aren't real contact fields — the tag renders as empty.\n\n# Available fields\n\n**Always available on a contact:** `first_name`, `last_name`, `email`, `phone`, `dob`.\n\n**Under `data.<key>`:** everything in `Custom Fields` (`GET /v3/custom_fields`). E.g. `{data.favorite_color}`, `{data.company}`.\n\n**Structured domain data (dot-path into an array's first element):**\n  - `{memberships.status}`, `{memberships.type}`, `{memberships.renewal_date}`, `{memberships.next_billing_date}`, `{memberships.price}`, `{memberships.sessions_remaining}`\n  - `{purchases.last_amount}`, `{purchases.all_products_purchased}`\n\n**Discover the full catalog** by calling `GET /v3/templates/merge_tags` (MCP: `describeMergeTags`). Returns three categories — Workroom Attributes (per-workroom contact fields), Special Attributes / Managed Links (short-link labels + `{unsubscribe_url}`), and Static Attributes (visits/purchases/appointments/workroom-info) — plus syntax examples and gotchas. Optional: `GET /v3/segments/schema` (`describeSegmentSchema`) has richer type/values info for segment-DSL fields, but for template merge tags prefer `describeMergeTags`.\n\nA tag that doesn't resolve renders as the empty string with no error. If you need a runtime placeholder (`{cta_url}`, `{promo_code}`, `{deadline}`), pass it through the campaign or notification `variables` object at send-time — the interpolator checks `variables` before contact fields.\n\n# Content shape by channel\n\n- **`sms`** — `body` (plain text, at most 10 segments: 1530 GSM characters, or 670 with emoji/other non-GSM characters; merge tags count as written. Keep merge-tag budget under 30 total chars vs. carrier segment cost).\n- **`email`** — `subject` + `body_html` (and optional `body_text` for plain-text alternative). Subject supports merge tags too. Use inline CSS; external stylesheets get stripped by many email clients.\n- **`voice`** — `script` (SSML or plain text) + `voice_id`.\n\nRequires the channel, subject and body content. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n\n**Names are not unique.** `name` has no uniqueness constraint — two templates (even the same channel, even the same account) can share the exact same name. Template names are not unique: creating one with an existing name succeeds, after which that name no longer identifies a single template.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateCreate"}}}},"responses":{"201":{"description":"Template created (in `draft` status).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Retrieve a template.

> Returns the template's live content - for email the stored \`template\_body\`, for SMS/voice the stored \`description\`, so edits made in the dashboard show up here. \`?version=\<n>\` (deprecated) fetches a historical snapshot taken by the old publish endpoint; \`?draft=true\` is accepted and ignored.\
> \
> \*\*This takes an \`id\`, not a name — there is no lookup-by-name endpoint.\*\* Template names are not unique (not even within a single channel/account), so a name alone can't be resolved to one template. Template names are not unique. \`GET /v3/templates?filter\[name]=\<name>\&filter\[channel]=\<channel>\` resolves a name, and may return more than one.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Template":{"type":"object","description":"Reusable message body. Channel-specific content fields (email uses `body_html`/`body_text`; SMS uses `body`; voice uses `script` + `voice_id`). Unused fields are null. `subject` is read-only/legacy - see its own description.\n","required":["id","object","name","channel","status","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/TemplateId"},"object":{"type":"string","const":"template"},"name":{"type":"string","maxLength":200},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"status":{"$ref":"#/components/schemas/TemplateStatus"},"version":{"type":"integer","description":"The template's current (live) version number. Bumped by every save, from the API or the dashboard."},"published_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate published version)."},"draft_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate draft)."},"subject":{"type":"string","nullable":true,"description":"Read-only legacy field - not settable via create/update. Templates have no subject line in the dashboard (that's a campaign-level concept); any value here is leftover from before that was enforced. Will be null on every template going forward."},"body_html":{"type":"string","nullable":true,"description":"Email only."},"body_text":{"type":"string","nullable":true,"description":"Email only. Recommended even when `body_html` is set."},"body":{"type":"string","nullable":true,"description":"SMS only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded."},"script":{"type":"string","nullable":true,"description":"Voice only. TTS script."},"voice_id":{"type":"string","nullable":true,"description":"Voice only. Provider-specific identifier. There is no default voice - required whenever `script` is set, and required before publish."},"from":{"$ref":"#/components/schemas/EmailAddress","nullable":true,"description":"Email only. Default sender."},"reply_to":{"$ref":"#/components/schemas/Email","nullable":true},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels (not contact tags)."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"TemplateChannel":{"type":"string","enum":["email","sms","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"TemplateStatus":{"type":"string","enum":["active","archived"],"description":"Templates have no draft/publish lifecycle - same as the dashboard, every saved template is live: create and PATCH take effect immediately for the dashboard, campaigns, flows and sends. `active` — every live template (email templates are stored exactly as the dashboard's Save writes them: `status: \"active\"`, `drafted: false`). `archived` — only templates flag-archived by an older API version (`DELETE` now really deletes); resolvable with `?include_archived=true`. Earlier API versions returned `draft` / `published`; both now read as `active`, and `filter[status]=draft|published|active` all list every live template.\n"},"EmailAddress":{"type":"object","required":["email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"}}},"Email":{"type":"string","format":"email"},"TemplateVariable":{"type":"object","required":["name","type"],"description":"Declared variable for the template. Variables are Liquid-interpolated at render time. Undeclared variables are still substituted if passed, but declared variables get validation + default handling.\n","properties":{"name":{"type":"string","description":"Variable name in Liquid form, e.g. `contact.first_name`, `booking_time`.","pattern":"^[a-zA-Z_][a-zA-Z0-9_.]*$"},"type":{"$ref":"#/components/schemas/TemplateVariableType"},"required":{"type":"boolean","default":false},"default":{"type":["string","number","boolean","null"],"description":"Fallback value if the variable is not provided at render time. Its type should match the variable's declared `type`."},"description":{"type":"string","maxLength":500}}},"TemplateVariableType":{"type":"string","enum":["string","number","boolean","date","url"]},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/{id}":{"get":{"tags":["Templates"],"operationId":"retrieveTemplate","summary":"Retrieve a template.","description":"Returns the template's live content - for email the stored `template_body`, for SMS/voice the stored `description`, so edits made in the dashboard show up here. `?version=<n>` (deprecated) fetches a historical snapshot taken by the old publish endpoint; `?draft=true` is accepted and ignored.\n\n**This takes an `id`, not a name — there is no lookup-by-name endpoint.** Template names are not unique (not even within a single channel/account), so a name alone can't be resolved to one template. Template names are not unique. `GET /v3/templates?filter[name]=<name>&filter[channel]=<channel>` resolves a name, and may return more than one.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"version","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"draft","in":"query","required":false,"schema":{"type":"boolean","default":false},"deprecated":true,"description":"Ignored - templates have no separate draft."}],"responses":{"200":{"description":"The template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Update a template.

> \*\*Changes the live template used by campaigns and sends\*\*, immediately and with no undo: the previous content is not kept (no version snapshot is taken), so the old wording cannot be restored from the API.\
> \
> Live immediately, exactly like saving in the dashboard: the fields the dashboard, the Inbox / v1 template pickers, campaign creation and sends read (\`template\_body\` / \`template\_json\` for email, \`description\` for SMS and voice) are written by this call, and the version number is bumped. There is no draft and no publish step. A campaign that already copied the template's content keeps its own copy. \`channel\` cannot be changed — create a new template instead.\
> \
> Email: when \`body\_html\` changes, the stored Bee design (\`template\_json\`) is regenerated only if it is still the one the API synthesized; a design saved later in the dashboard's Bee editor is left untouched (\`body\_html\` is then what sends, until the design is saved again in the dashboard).\
> \
> To move the template into (or out of) a folder, set \`folder\_id\` (pass \`null\` to unfolder it) — call \`GET /v3/templates/folders\` first and let the user choose from the existing list (or confirm a new one) rather than guessing a folder name.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"TemplateUpdate":{"type":"object","description":"Partial update, live immediately (no draft). `channel` is immutable.\n","properties":{"name":{"type":"string","maxLength":200},"body_html":{"type":"string","nullable":true},"body_text":{"type":"string","nullable":true},"body":{"type":"string","nullable":true,"maxLength":1530,"description":"SMS templates only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long`."},"script":{"type":"string","nullable":true},"voice_id":{"type":"string","nullable":true,"description":"TTS voice for the script - there is no default voice, so a voice template without one cannot be sent."},"from":{"$ref":"#/components/schemas/EmailAddress","nullable":true},"reply_to":{"$ref":"#/components/schemas/Email","nullable":true},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels. Prefer `folder_id` to move the template between folders. If `folder_id` is omitted but `tags` is a non-empty array, the FIRST entry is also resolved as a folder (id or name, find-or-create) - same fallback as `folder_id`, for callers that can only send `tags`. An empty `tags` array does NOT unfolder the template (that requires `folder_id: null`)."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"},"folder_id":{"type":"string","nullable":true,"description":"Move this template into (or out of) a folder, by id (tfd_...) or by name. An unrecognized name auto-creates a new folder - call GET /v3/templates/folders first and let the user choose from the existing list (or confirm a new one) instead of guessing a name. Pass `null` to unfolder it; omit to leave it where it is. Takes priority over any folder inferred from `tags[0]`."}}},"EmailAddress":{"type":"object","required":["email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"}}},"Email":{"type":"string","format":"email"},"TemplateVariable":{"type":"object","required":["name","type"],"description":"Declared variable for the template. Variables are Liquid-interpolated at render time. Undeclared variables are still substituted if passed, but declared variables get validation + default handling.\n","properties":{"name":{"type":"string","description":"Variable name in Liquid form, e.g. `contact.first_name`, `booking_time`.","pattern":"^[a-zA-Z_][a-zA-Z0-9_.]*$"},"type":{"$ref":"#/components/schemas/TemplateVariableType"},"required":{"type":"boolean","default":false},"default":{"type":["string","number","boolean","null"],"description":"Fallback value if the variable is not provided at render time. Its type should match the variable's declared `type`."},"description":{"type":"string","maxLength":500}}},"TemplateVariableType":{"type":"string","enum":["string","number","boolean","date","url"]},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Template":{"type":"object","description":"Reusable message body. Channel-specific content fields (email uses `body_html`/`body_text`; SMS uses `body`; voice uses `script` + `voice_id`). Unused fields are null. `subject` is read-only/legacy - see its own description.\n","required":["id","object","name","channel","status","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/TemplateId"},"object":{"type":"string","const":"template"},"name":{"type":"string","maxLength":200},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"status":{"$ref":"#/components/schemas/TemplateStatus"},"version":{"type":"integer","description":"The template's current (live) version number. Bumped by every save, from the API or the dashboard."},"published_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate published version)."},"draft_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate draft)."},"subject":{"type":"string","nullable":true,"description":"Read-only legacy field - not settable via create/update. Templates have no subject line in the dashboard (that's a campaign-level concept); any value here is leftover from before that was enforced. Will be null on every template going forward."},"body_html":{"type":"string","nullable":true,"description":"Email only."},"body_text":{"type":"string","nullable":true,"description":"Email only. Recommended even when `body_html` is set."},"body":{"type":"string","nullable":true,"description":"SMS only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded."},"script":{"type":"string","nullable":true,"description":"Voice only. TTS script."},"voice_id":{"type":"string","nullable":true,"description":"Voice only. Provider-specific identifier. There is no default voice - required whenever `script` is set, and required before publish."},"from":{"$ref":"#/components/schemas/EmailAddress","nullable":true,"description":"Email only. Default sender."},"reply_to":{"$ref":"#/components/schemas/Email","nullable":true},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels (not contact tags)."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"TemplateChannel":{"type":"string","enum":["email","sms","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"TemplateStatus":{"type":"string","enum":["active","archived"],"description":"Templates have no draft/publish lifecycle - same as the dashboard, every saved template is live: create and PATCH take effect immediately for the dashboard, campaigns, flows and sends. `active` — every live template (email templates are stored exactly as the dashboard's Save writes them: `status: \"active\"`, `drafted: false`). `archived` — only templates flag-archived by an older API version (`DELETE` now really deletes); resolvable with `?include_archived=true`. Earlier API versions returned `draft` / `published`; both now read as `active`, and `filter[status]=draft|published|active` all list every live template.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/{id}":{"patch":{"tags":["Templates"],"operationId":"updateTemplate","summary":"Update a template.","description":"**Changes the live template used by campaigns and sends**, immediately and with no undo: the previous content is not kept (no version snapshot is taken), so the old wording cannot be restored from the API.\n\nLive immediately, exactly like saving in the dashboard: the fields the dashboard, the Inbox / v1 template pickers, campaign creation and sends read (`template_body` / `template_json` for email, `description` for SMS and voice) are written by this call, and the version number is bumped. There is no draft and no publish step. A campaign that already copied the template's content keeps its own copy. `channel` cannot be changed — create a new template instead.\n\nEmail: when `body_html` changes, the stored Bee design (`template_json`) is regenerated only if it is still the one the API synthesized; a design saved later in the dashboard's Bee editor is left untouched (`body_html` is then what sends, until the design is saved again in the dashboard).\n\nTo move the template into (or out of) a folder, set `folder_id` (pass `null` to unfolder it) — call `GET /v3/templates/folders` first and let the user choose from the existing list (or confirm a new one) rather than guessing a folder name.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateUpdate"}}}},"responses":{"200":{"description":"Updated (live). Returns the template with its new `version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Delete a template.

> Genuine, irreversible hard delete — the template document is removed entirely. An internal audit copy is retained for support/recovery purposes but is not restorable via this API; there is no undelete/unarchive action.\
> \
> \*\*This takes an \`id\`, not a name — there is no lookup-by-name endpoint.\*\* Template names are not unique (not even within a single channel/account), so a name alone can't be resolved to one template. Template names are not unique. \`GET /v3/templates?filter\[name]=\<name>\&filter\[channel]=\<channel>\` resolves a name, and may return more than one.\
> \
> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/templates/{id}":{"delete":{"tags":["Templates"],"operationId":"deleteTemplate","summary":"Delete a template.","description":"Genuine, irreversible hard delete — the template document is removed entirely. An internal audit copy is retained for support/recovery purposes but is not restorable via this API; there is no undelete/unarchive action.\n\n**This takes an `id`, not a name — there is no lookup-by-name endpoint.** Template names are not unique (not even within a single channel/account), so a name alone can't be resolved to one template. Template names are not unique. `GET /v3/templates?filter[name]=<name>&filter[channel]=<channel>` resolves a name, and may return more than one.\n\n**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Publish a template (deprecated no-op).

> \*\*Deprecated — no-op.\*\* Templates have no draft/publish lifecycle (the dashboard has none): create and PATCH are already live. Kept so existing callers keep working: returns \`200\` with the template unchanged. \`change\_summary\` is ignored.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Template":{"type":"object","description":"Reusable message body. Channel-specific content fields (email uses `body_html`/`body_text`; SMS uses `body`; voice uses `script` + `voice_id`). Unused fields are null. `subject` is read-only/legacy - see its own description.\n","required":["id","object","name","channel","status","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/TemplateId"},"object":{"type":"string","const":"template"},"name":{"type":"string","maxLength":200},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"status":{"$ref":"#/components/schemas/TemplateStatus"},"version":{"type":"integer","description":"The template's current (live) version number. Bumped by every save, from the API or the dashboard."},"published_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate published version)."},"draft_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate draft)."},"subject":{"type":"string","nullable":true,"description":"Read-only legacy field - not settable via create/update. Templates have no subject line in the dashboard (that's a campaign-level concept); any value here is leftover from before that was enforced. Will be null on every template going forward."},"body_html":{"type":"string","nullable":true,"description":"Email only."},"body_text":{"type":"string","nullable":true,"description":"Email only. Recommended even when `body_html` is set."},"body":{"type":"string","nullable":true,"description":"SMS only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded."},"script":{"type":"string","nullable":true,"description":"Voice only. TTS script."},"voice_id":{"type":"string","nullable":true,"description":"Voice only. Provider-specific identifier. There is no default voice - required whenever `script` is set, and required before publish."},"from":{"$ref":"#/components/schemas/EmailAddress","nullable":true,"description":"Email only. Default sender."},"reply_to":{"$ref":"#/components/schemas/Email","nullable":true},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels (not contact tags)."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"TemplateChannel":{"type":"string","enum":["email","sms","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"TemplateStatus":{"type":"string","enum":["active","archived"],"description":"Templates have no draft/publish lifecycle - same as the dashboard, every saved template is live: create and PATCH take effect immediately for the dashboard, campaigns, flows and sends. `active` — every live template (email templates are stored exactly as the dashboard's Save writes them: `status: \"active\"`, `drafted: false`). `archived` — only templates flag-archived by an older API version (`DELETE` now really deletes); resolvable with `?include_archived=true`. Earlier API versions returned `draft` / `published`; both now read as `active`, and `filter[status]=draft|published|active` all list every live template.\n"},"EmailAddress":{"type":"object","required":["email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"}}},"Email":{"type":"string","format":"email"},"TemplateVariable":{"type":"object","required":["name","type"],"description":"Declared variable for the template. Variables are Liquid-interpolated at render time. Undeclared variables are still substituted if passed, but declared variables get validation + default handling.\n","properties":{"name":{"type":"string","description":"Variable name in Liquid form, e.g. `contact.first_name`, `booking_time`.","pattern":"^[a-zA-Z_][a-zA-Z0-9_.]*$"},"type":{"$ref":"#/components/schemas/TemplateVariableType"},"required":{"type":"boolean","default":false},"default":{"type":["string","number","boolean","null"],"description":"Fallback value if the variable is not provided at render time. Its type should match the variable's declared `type`."},"description":{"type":"string","maxLength":500}}},"TemplateVariableType":{"type":"string","enum":["string","number","boolean","date","url"]},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/{id}/publish":{"post":{"tags":["Templates"],"operationId":"publishTemplate","summary":"Publish a template (deprecated no-op).","deprecated":true,"description":"**Deprecated — no-op.** Templates have no draft/publish lifecycle (the dashboard has none): create and PATCH are already live. Kept so existing callers keep working: returns `200` with the template unchanged. `change_summary` is ignored.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"change_summary":{"type":"string","maxLength":500,"description":"Optional note describing what changed in this version."}}}}}},"responses":{"200":{"description":"The template, unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Duplicate a template.

> Creates a new, live template with a copy of the source's current content (including templates made in the dashboard). The source is not modified.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Template":{"type":"object","description":"Reusable message body. Channel-specific content fields (email uses `body_html`/`body_text`; SMS uses `body`; voice uses `script` + `voice_id`). Unused fields are null. `subject` is read-only/legacy - see its own description.\n","required":["id","object","name","channel","status","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/TemplateId"},"object":{"type":"string","const":"template"},"name":{"type":"string","maxLength":200},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"status":{"$ref":"#/components/schemas/TemplateStatus"},"version":{"type":"integer","description":"The template's current (live) version number. Bumped by every save, from the API or the dashboard."},"published_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate published version)."},"draft_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate draft)."},"subject":{"type":"string","nullable":true,"description":"Read-only legacy field - not settable via create/update. Templates have no subject line in the dashboard (that's a campaign-level concept); any value here is leftover from before that was enforced. Will be null on every template going forward."},"body_html":{"type":"string","nullable":true,"description":"Email only."},"body_text":{"type":"string","nullable":true,"description":"Email only. Recommended even when `body_html` is set."},"body":{"type":"string","nullable":true,"description":"SMS only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded."},"script":{"type":"string","nullable":true,"description":"Voice only. TTS script."},"voice_id":{"type":"string","nullable":true,"description":"Voice only. Provider-specific identifier. There is no default voice - required whenever `script` is set, and required before publish."},"from":{"$ref":"#/components/schemas/EmailAddress","nullable":true,"description":"Email only. Default sender."},"reply_to":{"$ref":"#/components/schemas/Email","nullable":true},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels (not contact tags)."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"TemplateChannel":{"type":"string","enum":["email","sms","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"TemplateStatus":{"type":"string","enum":["active","archived"],"description":"Templates have no draft/publish lifecycle - same as the dashboard, every saved template is live: create and PATCH take effect immediately for the dashboard, campaigns, flows and sends. `active` — every live template (email templates are stored exactly as the dashboard's Save writes them: `status: \"active\"`, `drafted: false`). `archived` — only templates flag-archived by an older API version (`DELETE` now really deletes); resolvable with `?include_archived=true`. Earlier API versions returned `draft` / `published`; both now read as `active`, and `filter[status]=draft|published|active` all list every live template.\n"},"EmailAddress":{"type":"object","required":["email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"}}},"Email":{"type":"string","format":"email"},"TemplateVariable":{"type":"object","required":["name","type"],"description":"Declared variable for the template. Variables are Liquid-interpolated at render time. Undeclared variables are still substituted if passed, but declared variables get validation + default handling.\n","properties":{"name":{"type":"string","description":"Variable name in Liquid form, e.g. `contact.first_name`, `booking_time`.","pattern":"^[a-zA-Z_][a-zA-Z0-9_.]*$"},"type":{"$ref":"#/components/schemas/TemplateVariableType"},"required":{"type":"boolean","default":false},"default":{"type":["string","number","boolean","null"],"description":"Fallback value if the variable is not provided at render time. Its type should match the variable's declared `type`."},"description":{"type":"string","maxLength":500}}},"TemplateVariableType":{"type":"string","enum":["string","number","boolean","date","url"]},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/{id}/duplicate":{"post":{"tags":["Templates"],"operationId":"duplicateTemplate","summary":"Duplicate a template.","description":"Creates a new, live template with a copy of the source's current content (including templates made in the dashboard). The source is not modified.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the duplicate. Defaults to `\"<source name> (copy)\"`."}}}}}},"responses":{"201":{"description":"Duplicate created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## List versions of a template (deprecated).

> \*\*Deprecated\*\* — templates have no draft/publish lifecycle, so no new snapshots are taken. Returns the current version first (\`is\_published: true\` — it is the live content), followed by any snapshots taken by the old publish endpoint (\`is\_published: false\`), newest first. Fetch one via \`GET /v3/templates/{id}/versions/{version}\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"TemplateVersionSummary":{"type":"object","required":["version","is_published","created_at"],"properties":{"version":{"type":"integer"},"is_published":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_by_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"change_summary":{"type":"string","nullable":true,"description":"Change note supplied to the (now deprecated) publish call, for historical versions."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"UserId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/{id}/versions":{"get":{"tags":["Templates"],"operationId":"listTemplateVersions","summary":"List versions of a template (deprecated).","deprecated":true,"description":"**Deprecated** — templates have no draft/publish lifecycle, so no new snapshots are taken. Returns the current version first (`is_published: true` — it is the live content), followed by any snapshots taken by the old publish endpoint (`is_published: false`), newest first. Fetch one via `GET /v3/templates/{id}/versions/{version}`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"List of versions.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVersionSummary"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Retrieve a specific template version (deprecated).

> \*\*Deprecated\*\* history. The current version number returns the live template; an older number returns the snapshot the old publish endpoint took at that version. No new snapshots are taken.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Template":{"type":"object","description":"Reusable message body. Channel-specific content fields (email uses `body_html`/`body_text`; SMS uses `body`; voice uses `script` + `voice_id`). Unused fields are null. `subject` is read-only/legacy - see its own description.\n","required":["id","object","name","channel","status","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/TemplateId"},"object":{"type":"string","const":"template"},"name":{"type":"string","maxLength":200},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"status":{"$ref":"#/components/schemas/TemplateStatus"},"version":{"type":"integer","description":"The template's current (live) version number. Bumped by every save, from the API or the dashboard."},"published_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate published version)."},"draft_version":{"type":"integer","deprecated":true,"description":"Deprecated alias of `version` (there is no separate draft)."},"subject":{"type":"string","nullable":true,"description":"Read-only legacy field - not settable via create/update. Templates have no subject line in the dashboard (that's a campaign-level concept); any value here is leftover from before that was enforced. Will be null on every template going forward."},"body_html":{"type":"string","nullable":true,"description":"Email only."},"body_text":{"type":"string","nullable":true,"description":"Email only. Recommended even when `body_html` is set."},"body":{"type":"string","nullable":true,"description":"SMS only. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded."},"script":{"type":"string","nullable":true,"description":"Voice only. TTS script."},"voice_id":{"type":"string","nullable":true,"description":"Voice only. Provider-specific identifier. There is no default voice - required whenever `script` is set, and required before publish."},"from":{"$ref":"#/components/schemas/EmailAddress","nullable":true,"description":"Email only. Default sender."},"reply_to":{"$ref":"#/components/schemas/Email","nullable":true},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"}},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form organizational labels (not contact tags)."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"TemplateChannel":{"type":"string","enum":["email","sms","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"TemplateStatus":{"type":"string","enum":["active","archived"],"description":"Templates have no draft/publish lifecycle - same as the dashboard, every saved template is live: create and PATCH take effect immediately for the dashboard, campaigns, flows and sends. `active` — every live template (email templates are stored exactly as the dashboard's Save writes them: `status: \"active\"`, `drafted: false`). `archived` — only templates flag-archived by an older API version (`DELETE` now really deletes); resolvable with `?include_archived=true`. Earlier API versions returned `draft` / `published`; both now read as `active`, and `filter[status]=draft|published|active` all list every live template.\n"},"EmailAddress":{"type":"object","required":["email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"}}},"Email":{"type":"string","format":"email"},"TemplateVariable":{"type":"object","required":["name","type"],"description":"Declared variable for the template. Variables are Liquid-interpolated at render time. Undeclared variables are still substituted if passed, but declared variables get validation + default handling.\n","properties":{"name":{"type":"string","description":"Variable name in Liquid form, e.g. `contact.first_name`, `booking_time`.","pattern":"^[a-zA-Z_][a-zA-Z0-9_.]*$"},"type":{"$ref":"#/components/schemas/TemplateVariableType"},"required":{"type":"boolean","default":false},"default":{"type":["string","number","boolean","null"],"description":"Fallback value if the variable is not provided at render time. Its type should match the variable's declared `type`."},"description":{"type":"string","maxLength":500}}},"TemplateVariableType":{"type":"string","enum":["string","number","boolean","date","url"]},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/{id}/versions/{version}":{"get":{"tags":["Templates"],"operationId":"retrieveTemplateVersion","summary":"Retrieve a specific template version (deprecated).","deprecated":true,"description":"**Deprecated** history. The current version number returns the live template; an older number returns the snapshot the old publish endpoint took at that version. No new snapshots are taken.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"The version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Render the template with sample variables (no send).

> Interpolates the template's live body with the provided variables and returns the rendered output, using the same merge-tag rules as the send workers (account timezone and default date formats, \`format="..."\` directives, managed links, static tags such as \`{workroom\_name}\` / \`{responsible.name}\`). Caller \`variables\` win over everything else. Tags that need a contact (e.g. \`{first\_name}\`, \`{total\_visits}\`) render their default or empty here; \`{coupon.\<id>}\` is never assigned by a preview. Nothing is sent. Rate limit bucket: \`read\`.\
> \
> A read: requires \`templates:read\` (a token with only \`templates:write\` is also accepted) and, for OAuth tokens, the dashboard role's Templates → View permission on this template.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"TemplatePreviewRequest":{"type":"object","description":"Render the template with sample variables. Does not send anything.","properties":{"variables":{"type":"object","additionalProperties":true,"description":"Variable values for interpolation. Missing declared variables use their `default` if set."},"version":{"type":"integer","nullable":true,"description":"Which version to render. Defaults to the current draft."}}},"TemplatePreviewResponse":{"type":"object","required":["object","channel","rendered"],"properties":{"object":{"type":"string","const":"template_preview"},"channel":{"$ref":"#/components/schemas/TemplateChannel"},"rendered":{"type":"object","description":"Channel-specific rendered output. Only the relevant channel's fields are populated.","properties":{"subject":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"body_text":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"script":{"type":"string","nullable":true}}},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-fatal rendering issues (undefined variables, formatting warnings)."}}},"TemplateChannel":{"type":"string","enum":["email","sms","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/templates/{id}/preview":{"post":{"tags":["Templates"],"operationId":"previewTemplate","summary":"Render the template with sample variables (no send).","description":"Interpolates the template's live body with the provided variables and returns the rendered output, using the same merge-tag rules as the send workers (account timezone and default date formats, `format=\"...\"` directives, managed links, static tags such as `{workroom_name}` / `{responsible.name}`). Caller `variables` win over everything else. Tags that need a contact (e.g. `{first_name}`, `{total_visits}`) render their default or empty here; `{coupon.<id>}` is never assigned by a preview. Nothing is sent. Rate limit bucket: `read`.\n\nA read: requires `templates:read` (a token with only `templates:write` is also accepted) and, for OAuth tokens, the dashboard role's Templates → View permission on this template.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplatePreviewRequest"}}}},"responses":{"200":{"description":"Rendered preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplatePreviewResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Send a test rendering to a specific address.

> Renders the template and sends to a single recipient for QA. Bypasses opt-in enforcement (recipient assumed to be an admin/tester). Test sends are tagged \`category: transactional\` on the resulting Message and are excluded from campaign/template analytics. \`Idempotency-Key\` is required. Rate limit bucket: \`messaging\`.\
> \
> \*\*Still a real send.\*\* Delivers to whichever address is given.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Templates","description":"Reusable message bodies for email, SMS, and voice. Draft/publish versioning; preview and test-send before shipping. Referenced by Campaigns, Flows, and Notifications."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["templates:write","messaging:send"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"TemplateTestSendRequest":{"type":"object","required":["to"],"description":"Send a rendered test to a specific address. Bypasses opt-in checks (recipient is assumed to be an admin/tester).","properties":{"to":{"$ref":"#/components/schemas/NotificationRecipient"},"variables":{"type":"object","additionalProperties":true},"version":{"type":"integer","nullable":true,"description":"Which version to render. Defaults to the current draft."}}},"NotificationRecipient":{"type":"object","description":"Recipient selector. Exactly one of `contact_id`, `phone`, or `email` must be set. If a raw `phone` or `email` doesn't match an existing contact, an unmanaged contact is auto-created (visible in dashboard, excluded from marketing lists).\n","properties":{"contact_id":{"$ref":"#/components/schemas/ContactId"},"phone":{"$ref":"#/components/schemas/PhoneE164"},"email":{"$ref":"#/components/schemas/Email"}},"oneOf":[{"required":["contact_id"]},{"required":["phone"]},{"required":["email"]}]},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Email":{"type":"string","format":"email"},"Message":{"type":"object","description":"A single message record — the outcome of a notification send, an outbound message from a campaign or flow, or a message inside a conversation. Same shape regardless of origin.\n","required":["id","object","channel","status","to","category","created_at"],"properties":{"id":{"$ref":"#/components/schemas/MessageId"},"object":{"type":"string","const":"message"},"channel":{"$ref":"#/components/schemas/MessageChannel"},"status":{"$ref":"#/components/schemas/MessageStatus"},"category":{"$ref":"#/components/schemas/MessageCategory"},"direction":{"type":"string","enum":["outbound","inbound"]},"conversation_id":{"type":"string","nullable":true,"description":"If this message is part of a conversation, its ID. Transactional sends default to null."},"to":{"type":"object","description":"Resolved recipient at send time.","properties":{"contact_id":{"$ref":"#/components/schemas/ContactId"},"phone":{"$ref":"#/components/schemas/PhoneE164"},"email":{"$ref":"#/components/schemas/Email"}}},"from":{"type":"object","nullable":true,"description":"Sender identity used for this send.","additionalProperties":true},"template_id":{"$ref":"#/components/schemas/TemplateId","nullable":true},"template_version":{"type":"integer","nullable":true,"description":"Which version of the template was rendered."},"subject":{"type":"string","nullable":true,"description":"Email only."},"body_snippet":{"type":"string","nullable":true,"description":"First ~200 chars of the rendered body, for previews."},"variables":{"type":"object","additionalProperties":true,"description":"Variables that were passed at send time (echoed for debugging)."},"provider":{"type":"string","nullable":true,"description":"Underlying delivery provider (`twilio`, `telnyx`, `mailgun`, etc.). Informational."},"provider_message_id":{"type":"string","nullable":true},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"cost":{"type":"object","nullable":true,"description":"Metered cost of this send in account currency.","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"sent_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"delivered_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"opened_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"clicked_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"failed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"MessageId":{"type":"string","pattern":"^msg_[0-9a-f]{24}$"},"MessageChannel":{"type":"string","enum":["sms","email","voice"],"description":"Delivery channel. Push is not supported by Gleantap."},"MessageStatus":{"type":"string","enum":["pending","queued","sending","sent","success","delivered","opened","clicked","failed","bounced","undelivered"],"description":"A v3 send lands in the shared `messages` collection as `pending` — that collection's own queued state — and a delivery worker moves it to `success` or `failed`.\n\nCampaign-pipeline sends use the richer lifecycle: `queued` → `sending` → `sent` → `delivered` (or `bounced`/`failed`/`undelivered`). `opened` / `clicked` follow `delivered` for email and for SMS with tracked links. Terminal states: `success`, `delivered`, `opened`, `clicked`, `failed`, `bounced`, `undelivered`. Not every channel produces all of them.\n"},"MessageCategory":{"type":"string","enum":["transactional","marketing"],"description":"Does NOT bypass opt-out. As in the dashboard's one-to-one sends, a contact who has opted out of SMS (STOP / `optin_sms: 0`) gets no SMS and a contact who has unsubscribed from email (`optout_email: 1`) gets no email, whatever the category — both return 422 `compliance_block` (`opted_out_all` likewise blocks every channel). `marketing` additionally suppresses addresses the dashboard's campaign audience excludes: `invalid_email` 2/3/4 (bounced, complained, inactive) and `invalid_phone: 1`, returning 422 `compliance_block`; marketing email also carries the workroom's unsubscribe/address footers. Voice opt-out (`optout_voice`) still blocks marketing only. Earlier versions let `transactional` (the default) bypass channel opt-out; that bypass is gone.\n"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"Rate limited.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"headers":{"RetryAfter":{"description":"On 429, seconds to wait before retrying.","schema":{"type":"integer"}}}},"paths":{"/templates/{id}/test_send":{"post":{"tags":["Templates"],"operationId":"testSendTemplate","summary":"Send a test rendering to a specific address.","description":"Renders the template and sends to a single recipient for QA. Bypasses opt-in enforcement (recipient assumed to be an admin/tester). Test sends are tagged `category: transactional` on the resulting Message and are excluded from campaign/template analytics. `Idempotency-Key` is required. Rate limit bucket: `messaging`.\n\n**Still a real send.** Delivers to whichever address is given.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateTestSendRequest"}}}},"responses":{"201":{"description":"Test send accepted. Returns the Message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```
