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

# Messages

Individual message records — the result of a notification send or a conversation reply — plus `/messages/report`, which aggregates them into delivery and engagement figures.

{% hint style="info" %}
**Opens and clicks are unique-only.** Only a contact's first open of a message is recorded, because mail clients, link scanners, and Apple Mail Privacy Protection trigger the tracking pixel repeatedly. **SMS has no open tracking**, so `opened` is always zero for SMS.
{% endhint %}

## Delivery and engagement, aggregated.

> How email and SMS sends performed — deliveries, bounces, drops, opens and clicks, with the rates derived from them. Aggregates the per-message send records, so it reflects individual messages rather than campaign-level rollups, and can therefore break down by day, location and flow.\
> \
> Pass \`group\_by\` for a breakdown — \`day\`, \`location\`, \`channel\`, \`campaign\`, \`flow\` or \`campaign\_type\`. For \`campaign\` and \`flow\` the group key comes back as a prefixed id, so it can be passed straight back as a filter to drill in. Every grouping partitions the same population, so a grouping's \`sent\` values sum to the summary's.\
> \
> \`sent\` / \`delivered\` use the dashboard's own definitions (see \`MessageMetrics\`); \`attempted\` is every dispatched message. For SMS, delivery is the carrier outcome, not the provider handoff.\
> \
> \`group\_by=day\` buckets by calendar day in the workroom timezone, like the dashboard's trend chart: sends by the day they were sent, and \`opened\` / \`clicked\` / \`unsubscribed\` by the day that event happened (inside the window, for messages sent in the window).\
> \
> Filters and \`group\_by\` compose, so "open rate by location for one flow last month" is a single call. Filters are accepted either bare (\`?channel=email\`) or as \`filter\[channel]=email\`.\
> \
> \`campaign\_type\` separates sends someone launched as a campaign from sends a flow produced. Flow sends are shadow campaigns — a flow's message node has a paired campaign record — so both live together and are told apart by that link, not by where they are stored.\
> \
> \*\*Always bounded.\*\* Without \`since\`/\`until\` this reports the last 30 days; the widest accepted window is 366 days. Bare dates are read in the workroom timezone (date-only \`until\` = end of that day), matching the dashboard's reports.\
> \
> Opens and clicks are unique-only, and SMS has no open tracking — see the resource description before comparing these to another system's figures.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Messages","description":"Individual message records — the outcome of a notification send or a conversation reply — plus `/messages/report`, which aggregates them into delivery and engagement figures.\n\nTwo properties of the underlying data are worth knowing before reading any engagement number. **Opens and clicks are unique-only.** The open-tracking pixel deliberately records only a contact's first open of a message, because mail clients, link scanners and Apple Mail Privacy Protection hit the pixel repeatedly; repeat opens are discarded at source, so no total-opens figure exists to be reported. And **SMS has no open tracking at all**, so `opened` on an SMS bucket is structurally zero rather than merely unobserved.\n\nPhase 1 exposes retrieval only; full Conversations resource lands in Phase 2.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["campaigns: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":{"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"FlowId":{"type":"string","pattern":"^flw_[0-9a-f]{24}$"},"MessageReport":{"type":"object","description":"Delivery and engagement totals for a window.","properties":{"object":{"type":"string","enum":["message_report"]},"window":{"type":"object","description":"The window actually reported on, resolved and echoed back. Bare dates are read in the workroom timezone, as the dashboard's reports do (`until` = end of that day).","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}},"channels":{"type":"array","description":"Which channels were included.","items":{"type":"string","enum":["email","sms"]}},"summary":{"$ref":"#/components/schemas/MessageMetrics"}}},"MessageMetrics":{"type":"object","description":"Delivery and engagement counters, plus the rates derived from them. Every rate is a percentage and names its own denominator, because there is no single convention and callers otherwise disagree quietly.\n","properties":{"attempted":{"type":"integer","description":"Every message dispatched in the window","whatever happened to it (queued-but-unsent records are not counted). The outcomes below add up to this.":null},"sent":{"type":"integer","description":"Same definition as the dashboard's \"Emails Sent\" / \"SMS Sent\": status `success` or `delivered`. Excludes bounced/failed/dropped and spam-complaint rows."},"delivered":{"type":"integer","description":"Email: status `success` or `delivered` (equal to `sent`; a spam complaint is counted under `complaints`, as the dashboard does). SMS: the carrier outcome `messagestatus` is `delivered`/`delivery_unconfirmed` — `status: success` only means handed off to the provider."},"bounced":{"type":"integer","description":"Email: hard bounce reported by the provider. SMS: `messagestatus` undelivered / delivery_failed / sending_failed."},"dropped":{"type":"integer"},"undelivered":{"type":"integer","description":"Returned out of band."},"delayed":{"type":"integer","description":"Transient failure","still being retried.":null},"failed":{"type":"integer","description":"Email: refused on policy. SMS: `messagestatus` failed, or failed at send time."},"unaccounted":{"type":"integer","description":"Sends whose outcome is none of the above (nor a spam complaint). The outcomes add up to `attempted` and this is the remainder — for SMS mostly messages handed off with no carrier result yet; for email a provider status this report does not yet know about.\n"},"complaints":{"type":"integer","description":"Spam complaints. Two webhook paths record one; both are counted."},"unsubscribed":{"type":"integer","description":"Unsubscribes attributed to this message."},"campaigns":{"type":"integer","description":"Distinct campaigns that sent into this bucket."},"flows":{"type":"integer","description":"Distinct flows that sent into this bucket."},"opened":{"type":"integer","description":"Distinct contacts who opened. Unique-only — see the resource description. Always 0 for SMS."},"clicked":{"type":"integer","description":"Distinct contacts who clicked. Unique-only."},"contacts":{"type":"integer","description":"Distinct contacts reached. A contact sent two messages counts once here and twice in `sent`."},"delivery_rate":{"type":"number","description":"delivered / sent."},"bounce_rate":{"type":"number","description":"bounced / attempted."},"drop_rate":{"type":"number","description":"dropped / attempted."},"open_rate":{"type":"number","description":"opened / delivered."},"click_rate":{"type":"number","description":"clicked / delivered."},"click_to_open_rate":{"type":"number","description":"clicked / opened."},"spam_rate":{"type":"number","description":"complaints / delivered — nobody can complain about a message that bounced."},"unsubscribe_rate":{"type":"number","description":"unsubscribed / delivered."}}},"MessageReportGrouped":{"type":"object","description":"The same figures broken out on one dimension. Returned instead of the bare summary whenever `group_by` is passed.","properties":{"object":{"type":"string","enum":["message_report_grouped"]},"window":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}},"channels":{"type":"array","items":{"type":"string","enum":["email","sms"]}},"group_by":{"type":"string"},"summary":{"$ref":"#/components/schemas/MessageMetrics"},"groups":{"type":"array","description":"Ordered by `sent`, except `group_by=day`, which is chronological. Capped at 500 groups. Each grouping partitions the same population, so the groups' `sent` sums to the summary's.\n","items":{"allOf":[{"type":"object","properties":{"key":{"type":"string","description":"The dimension value. `(none)` when the record carries no value for it. For `campaign` and `flow` this is a prefixed id, so it can be passed straight back as the `campaign_id` / `flow_id` filter.\n"}}},{"$ref":"#/components/schemas/MessageMetrics"}]}}}},"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":{"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":{"/messages/report":{"get":{"tags":["Messages"],"operationId":"getMessageReport","summary":"Delivery and engagement, aggregated.","description":"How email and SMS sends performed — deliveries, bounces, drops, opens and clicks, with the rates derived from them. Aggregates the per-message send records, so it reflects individual messages rather than campaign-level rollups, and can therefore break down by day, location and flow.\n\nPass `group_by` for a breakdown — `day`, `location`, `channel`, `campaign`, `flow` or `campaign_type`. For `campaign` and `flow` the group key comes back as a prefixed id, so it can be passed straight back as a filter to drill in. Every grouping partitions the same population, so a grouping's `sent` values sum to the summary's.\n\n`sent` / `delivered` use the dashboard's own definitions (see `MessageMetrics`); `attempted` is every dispatched message. For SMS, delivery is the carrier outcome, not the provider handoff.\n\n`group_by=day` buckets by calendar day in the workroom timezone, like the dashboard's trend chart: sends by the day they were sent, and `opened` / `clicked` / `unsubscribed` by the day that event happened (inside the window, for messages sent in the window).\n\nFilters and `group_by` compose, so \"open rate by location for one flow last month\" is a single call. Filters are accepted either bare (`?channel=email`) or as `filter[channel]=email`.\n\n`campaign_type` separates sends someone launched as a campaign from sends a flow produced. Flow sends are shadow campaigns — a flow's message node has a paired campaign record — so both live together and are told apart by that link, not by where they are stored.\n\n**Always bounded.** Without `since`/`until` this reports the last 30 days; the widest accepted window is 366 days. Bare dates are read in the workroom timezone (date-only `until` = end of that day), matching the dashboard's reports.\n\nOpens and clicks are unique-only, and SMS has no open tracking — see the resource description before comparing these to another system's figures.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"group_by","in":"query","description":"Break the figures out on this dimension instead of returning totals only.","schema":{"type":"string","enum":["day","location","channel","campaign","flow","campaign_type"]}},{"name":"since","in":"query","description":"Start of the window, inclusive. Defaults to 30 days before `until`. Read as UTC unless an offset is given.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","description":"End of the window, inclusive. Defaults to now.","schema":{"type":"string","format":"date-time"}},{"name":"channel","in":"query","schema":{"type":"string","enum":["email","sms"]}},{"name":"campaign_type","in":"query","description":"`campaign` for sends launched directly; `flow` for sends a flow produced.","schema":{"type":"string","enum":["campaign","flow"]}},{"name":"campaign_id","in":"query","schema":{"$ref":"#/components/schemas/CampaignId"}},{"name":"flow_id","in":"query","schema":{"$ref":"#/components/schemas/FlowId"}},{"name":"location","in":"query","description":"The recipient's location, matched exactly and case-insensitively. Taken from the contact, since messages carry no location of their own.","schema":{"type":"string"}}],"responses":{"200":{"description":"Totals, or a breakdown when `group_by` was passed.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MessageReport"},{"$ref":"#/components/schemas/MessageReportGrouped"}]}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Retrieve a message.

> Fetch a single message record by ID. Works for messages produced by notifications, campaigns, flows, or inbound conversations — same shape everywhere.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Messages","description":"Individual message records — the outcome of a notification send or a conversation reply — plus `/messages/report`, which aggregates them into delivery and engagement figures.\n\nTwo properties of the underlying data are worth knowing before reading any engagement number. **Opens and clicks are unique-only.** The open-tracking pixel deliberately records only a contact's first open of a message, because mail clients, link scanners and Apple Mail Privacy Protection hit the pixel repeatedly; repeat opens are discarded at source, so no total-opens figure exists to be reported. And **SMS has no open tracking at all**, so `opened` on an SMS bucket is structurally zero rather than merely unobserved.\n\nPhase 1 exposes retrieval only; full Conversations resource lands in Phase 2.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["conversations: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"}},"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":{"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"},"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}$"},"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":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/messages/{id}":{"get":{"tags":["Messages"],"operationId":"retrieveMessage","summary":"Retrieve a message.","description":"Fetch a single message record by ID. Works for messages produced by notifications, campaigns, flows, or inbound conversations — same shape everywhere.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/FieldsParam"}],"responses":{"200":{"description":"The message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
