> 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/notifications.md).

# Notifications

Transactional send endpoints for SMS, email, and voice. One recipient per call. For opt-in-driven marketing use Campaigns; for multi-step sequences use Flows.

## Send an SMS to one recipient.

> Transactional SMS. Provide either \`template\_id\` or inline \`body\`. For opt-in-driven marketing use \`POST /v3/campaigns\`; for multi-step sequences use \`POST /v3/flows\`. \`Idempotency-Key\` is required — without it, a retry sends a duplicate. Returns 422 \`compliance\_block\` when the contact has opted out of SMS (any category — \`category: transactional\` does not bypass it), when the workroom's opt-in setting (allow sending to opted-in / double-opted-in only) excludes the contact, or for a marketing send to an \`invalid\_phone\` number; 422 \`insufficient\_sms\_credits\` when the account bills SMS against prepaid credits and has none left; 422 \`empty\_content\` when a template renders to nothing. The recipient number is formatted with the account's country code before sending. Once delivered the row carries the same fields as a dashboard inbox send (provider flag, \`messagesid\`, credit usage) and the contact's inbox preview is updated. Rate limit bucket: \`messaging\` (100 req/min).\
> \
> \*\*Sends to a real person the moment it is called.\*\* There is no recall. This goes to the one recipient specified here - not a segment or campaign audience.\
> \
> \*\*Where this lands.\*\* The message is written to the shared \`messages\` collection as \`status: "pending"\`, in that collection's own schema, carrying one extra attribute — \`v3\_api\` — naming the operation that created it (\`sendSMS\`/\`sendEmail\`/\`sendVoice\`). A delivery worker claims on \`{ v3\_api: { $exists: true }, status: "pending" }\` and sets \`status\` plus \`sent\_on\` when done. \`source\` deliberately keeps the collection's existing vocabulary (\`single\_chat\_sms\`/\`single\_chat\_email\`) so the send still appears in the inbox and is counted by SMS-credit billing.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Notifications","description":"Transactional send endpoints for SMS, email, and voice. One recipient per call. For opt-in-driven marketing use Campaigns; for multi-step sequences use Flows."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["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":{"NotificationSMS":{"type":"object","required":["to"],"description":"Send one SMS. Either `template_id` or `body` is required — not both. If neither is given, 400 `missing_content`. Include `Idempotency-Key` to avoid duplicate sends on retry.\n","properties":{"to":{"$ref":"#/components/schemas/NotificationRecipient"},"template_id":{"$ref":"#/components/schemas/TemplateId","description":"Reference an SMS template. Mutually exclusive with `body`."},"body":{"type":"string","maxLength":1530,"description":"Inline message body. Mutually exclusive with `template_id`. 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` (field `body`); a template body, or one that merge-tag values push over the limit once rendered, is rejected the same way (field `template_id` / `body`). MMS (with `media_url`) is not segment-checked."},"variables":{"type":"object","additionalProperties":true,"description":"Liquid variables. Used with `template_id` (ignored with inline `body`)."},"from":{"$ref":"#/components/schemas/PhoneNumberId","description":"The account's outbound phone number to send from. Omit to use the account default."},"media_url":{"type":"array","maxItems":10,"items":{"type":"string","format":"uri"},"description":"MMS media URLs (public http(s), fetched by the carrier) — sent as MMS through Twilio, Telnyx and Edgility the way the dashboard does; uses 2 extra SMS credits. An invalid URL returns 400. RingCentral workrooms cannot send MMS from v3."},"category":{"$ref":"#/components/schemas/MessageCategory","default":"transactional"}}},"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"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"PhoneNumberId":{"type":"string","pattern":"^pn_[0-9a-f]{24}$","description":"A phone number configured for a workroom (Twilio/Telnyx/etc.) — used as the SMS/voice sender."},"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"},"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"},"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"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","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"}}}},"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":{"/notifications/sms":{"post":{"tags":["Notifications"],"operationId":"sendSMS","summary":"Send an SMS to one recipient.","description":"Transactional SMS. Provide either `template_id` or inline `body`. For opt-in-driven marketing use `POST /v3/campaigns`; for multi-step sequences use `POST /v3/flows`. `Idempotency-Key` is required — without it, a retry sends a duplicate. Returns 422 `compliance_block` when the contact has opted out of SMS (any category — `category: transactional` does not bypass it), when the workroom's opt-in setting (allow sending to opted-in / double-opted-in only) excludes the contact, or for a marketing send to an `invalid_phone` number; 422 `insufficient_sms_credits` when the account bills SMS against prepaid credits and has none left; 422 `empty_content` when a template renders to nothing. The recipient number is formatted with the account's country code before sending. Once delivered the row carries the same fields as a dashboard inbox send (provider flag, `messagesid`, credit usage) and the contact's inbox preview is updated. Rate limit bucket: `messaging` (100 req/min).\n\n**Sends to a real person the moment it is called.** There is no recall. This goes to the one recipient specified here - not a segment or campaign audience.\n\n**Where this lands.** The message is written to the shared `messages` collection as `status: \"pending\"`, in that collection's own schema, carrying one extra attribute — `v3_api` — naming the operation that created it (`sendSMS`/`sendEmail`/`sendVoice`). A delivery worker claims on `{ v3_api: { $exists: true }, status: \"pending\" }` and sets `status` plus `sent_on` when done. `source` deliberately keeps the collection's existing vocabulary (`single_chat_sms`/`single_chat_email`) so the send still appears in the inbox and is counted by SMS-credit billing.\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/NotificationSMS"}}}},"responses":{"201":{"description":"Send accepted. Returns the created message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```

## Send an email to one recipient.

> Transactional email. Provide either \`template\_id\` or inline \`subject\` + \`body\_html\`/\`body\_text\` (with a template, an optional \`subject\` sets the subject line — templates carry none). Attachments are not supported (a request with \`attachments\` is rejected \`422\`). Returns 422 \`compliance\_block\` when the contact has unsubscribed from email (any category) or, for \`category: marketing\`, when the address is suppressed (\`invalid\_email\` 2/3/4); 422 \`empty\_content\` when the content renders to nothing. Marketing-category sends (and template/campaign test sends) get the workroom's unsubscribe and address footers, as the dashboard adds them; one-to-one transactional sends do not. The stored \`messages\` row follows the dashboard's layout: \`email\` is the sender, \`to\` the recipient. For marketing broadcasts use \`POST /v3/campaigns\`. \`Idempotency-Key\` is required. Rate limit bucket: \`messaging\`.\
> \
> \*\*Sends to a real person the moment it is called.\*\* There is no recall. This goes to the one recipient specified here - not a segment or campaign audience.\
> \
> \*\*Where this lands.\*\* The message is written to the shared \`messages\` collection as \`status: "pending"\`, in that collection's own schema, carrying one extra attribute — \`v3\_api\` — naming the operation that created it (\`sendSMS\`/\`sendEmail\`/\`sendVoice\`). A delivery worker claims on \`{ v3\_api: { $exists: true }, status: "pending" }\` and sets \`status\` plus \`sent\_on\` when done. \`source\` deliberately keeps the collection's existing vocabulary (\`single\_chat\_sms\`/\`single\_chat\_email\`) so the send still appears in the inbox and is counted by SMS-credit billing.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Notifications","description":"Transactional send endpoints for SMS, email, and voice. One recipient per call. For opt-in-driven marketing use Campaigns; for multi-step sequences use Flows."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["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":{"NotificationEmail":{"type":"object","required":["to"],"description":"Send one email. Either `template_id` or (`subject` + one of `body_html`/`body_text`) is required. Attachments are not supported: the send path cannot attach files, so a request carrying `attachments` is rejected with `422`. Link to the file from the body instead.\n","properties":{"to":{"$ref":"#/components/schemas/NotificationRecipient"},"template_id":{"$ref":"#/components/schemas/TemplateId","description":"Reference an email template. Mutually exclusive with inline `subject`/`body_html`/`body_text`."},"subject":{"type":"string","maxLength":500},"body_html":{"type":"string","description":"HTML body. At least one of `body_html` or `body_text` required if not using a template."},"body_text":{"type":"string","description":"Plain-text body. Used (sent as a text/plain email) only when `body_html` is absent; with `body_html` present the HTML is sent."},"variables":{"type":"object","additionalProperties":true},"from":{"$ref":"#/components/schemas/EmailAddress","description":"Sender. Must be a verified sender on the account. Omit to use the workroom's sender, chosen as the dashboard does (workroom from_email, else the primary user, else default_email)."},"reply_to":{"$ref":"#/components/schemas/Email","description":"Overrides the Reply-To. Without it the dashboard's rule applies (the sender's own reply-to, else the workroom reply_to_email / default_email)."},"cc":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/Email"},"description":"Delivered alongside the workroom's inbox auto-cc (cc_inbox_email_to); stored as `user_cc`."},"bcc":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/Email"},"description":"Delivered alongside the workroom's inbox auto-bcc (forward_inbox_email_copy); stored as `user_bcc`."},"attachments":{"type":"array","maxItems":0,"deprecated":true,"description":"Not supported — any non-empty value is rejected with `422 send_failed`. (Previously accepted and silently dropped: the email went out without the files.)"},"category":{"$ref":"#/components/schemas/MessageCategory","default":"transactional"}}},"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"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"EmailAddress":{"type":"object","required":["email"],"properties":{"name":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"}}},"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"},"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"},"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"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","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"}}}},"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":{"/notifications/email":{"post":{"tags":["Notifications"],"operationId":"sendEmail","summary":"Send an email to one recipient.","description":"Transactional email. Provide either `template_id` or inline `subject` + `body_html`/`body_text` (with a template, an optional `subject` sets the subject line — templates carry none). Attachments are not supported (a request with `attachments` is rejected `422`). Returns 422 `compliance_block` when the contact has unsubscribed from email (any category) or, for `category: marketing`, when the address is suppressed (`invalid_email` 2/3/4); 422 `empty_content` when the content renders to nothing. Marketing-category sends (and template/campaign test sends) get the workroom's unsubscribe and address footers, as the dashboard adds them; one-to-one transactional sends do not. The stored `messages` row follows the dashboard's layout: `email` is the sender, `to` the recipient. For marketing broadcasts use `POST /v3/campaigns`. `Idempotency-Key` is required. Rate limit bucket: `messaging`.\n\n**Sends to a real person the moment it is called.** There is no recall. This goes to the one recipient specified here - not a segment or campaign audience.\n\n**Where this lands.** The message is written to the shared `messages` collection as `status: \"pending\"`, in that collection's own schema, carrying one extra attribute — `v3_api` — naming the operation that created it (`sendSMS`/`sendEmail`/`sendVoice`). A delivery worker claims on `{ v3_api: { $exists: true }, status: \"pending\" }` and sets `status` plus `sent_on` when done. `source` deliberately keeps the collection's existing vocabulary (`single_chat_sms`/`single_chat_email`) so the send still appears in the inbox and is counted by SMS-credit billing.\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/NotificationEmail"}}}},"responses":{"201":{"description":"Send accepted. Returns the created message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```

## Place an outbound voice call.

> TTS voice call. Provide either \`template\_id\` (voice template with \`script\` + \`voice\_id\`) or inline \`script\` + \`voice\_id\`. Set \`machine\_detection: true\` to hang up on voicemail (adds \~1s latency). Recording URLs surface on the resulting \`Message\` when \`record: true\`. Rate limit bucket: \`messaging\`.\
> \
> \*\*Sends to a real person the moment it is called.\*\* There is no recall. This goes to the one recipient specified here - not a segment or campaign audience.\
> \
> \*\*Where this lands.\*\* The message is written to the shared \`messages\` collection as \`status: "pending"\`, in that collection's own schema, carrying one extra attribute — \`v3\_api\` — naming the operation that created it (\`sendSMS\`/\`sendEmail\`/\`sendVoice\`). A delivery worker claims on \`{ v3\_api: { $exists: true }, status: "pending" }\` and sets \`status\` plus \`sent\_on\` when done. \`source\` deliberately keeps the collection's existing vocabulary (\`single\_chat\_sms\`/\`single\_chat\_email\`) so the send still appears in the inbox and is counted by SMS-credit billing.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Notifications","description":"Transactional send endpoints for SMS, email, and voice. One recipient per call. For opt-in-driven marketing use Campaigns; for multi-step sequences use Flows."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["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":{"NotificationVoice":{"type":"object","required":["to"],"description":"Place one outbound voice call. Either `template_id` (voice template with `script` + `voice_id`) or inline `script` is required. Set `machine_detection: true` to only deliver if a human answers.\n","properties":{"to":{"$ref":"#/components/schemas/NotificationRecipient"},"template_id":{"$ref":"#/components/schemas/TemplateId","description":"Reference a voice template. Mutually exclusive with inline `script`."},"script":{"type":"string","description":"TTS script to speak. Mutually exclusive with `template_id`."},"voice_id":{"type":"string","description":"Voice identifier (provider-specific, e.g., `aura-asteria-en`). Required when `script` is inline."},"variables":{"type":"object","additionalProperties":true},"from":{"$ref":"#/components/schemas/PhoneNumberId","description":"Caller ID for the outbound call."},"machine_detection":{"type":"boolean","default":false,"description":"If true, hang up when an answering machine or voicemail is detected. Adds ~1s of latency to detect."},"record":{"type":"boolean","default":false,"description":"Record the call. Retention per account setting. Recording URL surfaced on the resulting `Message` when available."},"category":{"$ref":"#/components/schemas/MessageCategory","default":"transactional"}}},"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"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"PhoneNumberId":{"type":"string","pattern":"^pn_[0-9a-f]{24}$","description":"A phone number configured for a workroom (Twilio/Telnyx/etc.) — used as the SMS/voice sender."},"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"},"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"},"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"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","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"}}}},"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":{"/notifications/voice":{"post":{"tags":["Notifications"],"operationId":"sendVoice","summary":"Place an outbound voice call.","description":"TTS voice call. Provide either `template_id` (voice template with `script` + `voice_id`) or inline `script` + `voice_id`. Set `machine_detection: true` to hang up on voicemail (adds ~1s latency). Recording URLs surface on the resulting `Message` when `record: true`. Rate limit bucket: `messaging`.\n\n**Sends to a real person the moment it is called.** There is no recall. This goes to the one recipient specified here - not a segment or campaign audience.\n\n**Where this lands.** The message is written to the shared `messages` collection as `status: \"pending\"`, in that collection's own schema, carrying one extra attribute — `v3_api` — naming the operation that created it (`sendSMS`/`sendEmail`/`sendVoice`). A delivery worker claims on `{ v3_api: { $exists: true }, status: \"pending\" }` and sets `status` plus `sent_on` when done. `source` deliberately keeps the collection's existing vocabulary (`single_chat_sms`/`single_chat_email`) so the send still appears in the inbox and is counted by SMS-credit billing.\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/NotificationVoice"}}}},"responses":{"201":{"description":"Call queued. Returns the created message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```
