SUsuprsend

List Messages

Changed on

Retrieve a paginated list of messages in a workspace order by created_at desc. Can be used to fetch and show message logs on the platform.

get/v1/message/

Request

Query parameters

limitinteger

Maximum number of messages to return per page. Defaults to 10, maximum is 1000 (20 when include_content=true). Larger values are capped to the maximum.

afterstring

Cursor for forward pagination - pass the meta.after value from a previous response to fetch the next page of older messages. Treat this value as an opaque cursor - do not parse, validate, or assume any format for it. Takes precedence over before when both are set (before is silently ignored).

beforestring

Cursor for backward pagination - pass the meta.before value from a previous response to fetch the previous page of newer messages. Treat this value as an opaque cursor - do not parse, validate, or assume any format for it. Ignored when after is also set.

status[]string[]

Filter by one or more derived statuses. Multiple values are OR-ed. Repeat the param for each value, e.g. ?status[]=delivered&status[]=seen.

channel'sms' | 'email' | 'androidpush' | 'iospush' | 'webpush' | 'inbox' | 'whatsapp' | 'slack' | 'ms_teams'

Filter by delivery channel.

recipient_id[]string[]

Filter by one or more recipient distinct_ids (OR-ed). Repeat the param for each value, e.g. ?recipient_id[]=user_123&recipient_id[]=user_456.

category[]string[]

Filter by one or more notification categories (OR-ed). Repeat the param for each value, e.g. ?category[]=transactional&category[]=promotional.

created_at_gtestring date-time

RFC3339 timestamp lower bound (inclusive). Compared against the created_at column which has second precision - sub-second components in the filter value are effectively truncated. Example: 2026-04-26T21:34:33Z.

created_at_ltestring date-time

RFC3339 timestamp upper bound (inclusive). Same second-precision caveat as created_at_gte. Must be >= created_at_gte when both are set.

workflow_slugstring

Filter messages triggered from a specific workflow.

execution_idstring

Matches wf_exec_id or broadcast_id.

idempotency_keystring

Filter by the idempotency key associated with the message at trigger time.

message_idstring

Exact match on message ID.

tenant_idstring

Filter messages belonging to a specific tenant.

is_campaignboolean

Set true to return only messages sent as part of a broadcast/campaign.

object_idstring

Must be provided together with object_type to filter messages sent to an object. Will filter all message logs which were sent to recipients after object fanout.

object_typestring

Must be provided together with object_id to filter messages sent to an object. Will filter all message logs which were sent to recipients after object fanout.

include_contentboolean

Set true to include the rendered message content in each result object. When false (default), the content key is omitted from the response to keep payloads lightweight.

Response

Returns the paginated list of messages order by created_at desc.

Example response

{
  "results": [
    {
      "channel_identity": {
        "sms": "+15555550100"
      }
    }
  ]
}

Changes

  • 5f0169085547Revision changes
    • breaking

      removed the enum value unread (is_read = false) from the property items/ of the query request parameter status[]

    • warning

      added the new failure_by_vendor enum value to the // response property for the response status

    • warning

      added the new unread enum value to the // response property for the response status

    • info

      added the enum value unread (marked unread after being read unread_at later than read_at) to the property items/ of the query request parameter status[]

    • info

      removed the delivery_failure enum value from the // response property for the response status

  • e54dd32705e8Revision changes
    • breaking

      api path removed without deprecation

    • info

      endpoint added