---
title: "List Messages"
method: GET
path: "/v1/message/"
---

# List Messages

`GET /v1/message/`

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.

## Query parameters

- `limit` integer
- `after` string
- `before` string
- `status[]` string[]
- `channel` 'sms' | 'email' | 'androidpush' | 'iospush' | 'webpush' | 'inbox' | 'whatsapp' | 'slack' | 'ms_teams'
- `recipient_id[]` string[]
- `category[]` string[]
- `created_at_gte` string, date-time
- `created_at_lte` string, date-time
- `workflow_slug` string
- `execution_id` string
- `idempotency_key` string
- `message_id` string
- `tenant_id` string
- `is_campaign` boolean
- `object_id` string
- `object_type` string
- `include_content` boolean

## Response `200`

Returns the paginated list of messages order by created_at desc.

- object
  - `meta` CursorPagination
    - `count` integer — Total matching records (ignores cursor position).
    - `limit` integer — Maximum number of results returned per page.
    - `has_prev` boolean — True when the previous page (newer logs) exists.
    - `before` string, nullable — Cursor to pass as `before=` to retrieve the previous page (newer logs). Null on the first page or when `has_prev` is false.
    - `has_next` boolean — True when an next page (older logs) exist.
    - `after` string, nullable — Cursor to pass as `after=` to retrieve the next page (older logs). Null when `has_next` is false.
  - `results` MessageResponse[]
    - `message_id` string — Message-id to update.
    - `created_at` string, date-time — Time when the message entry was created.
    - `updated_at` string, date-time — Time when the message entry was last updated (for example, on a status or timestamp change).
    - `triggered_at` string, date-time, nullable — Time when the message was handovered to vendor by SuprSend.
    - `delivered_at` string, date-time, nullable — Time when the vendor confirmed successful delivery. Null if the message has not been delivered yet. If you're not getting delivery events for email, SMS and Whatsapp, make sure to configure SuprSend webhook URL in vendor portal.
    - `seen_at` string, date-time, nullable — Time when the recipient first saw or opened the message. Seen tracking is available for all channels accept Slack, MS Teams and SMS.
    - `clicked_at` string, date-time, nullable — Time when the recipient clicked or interacted with the message. Tracked for Email, Push and Inbox.
    - `dismissed_at` string, date-time, nullable — Time when the recipient dismissed or cleared the message. Only application for mobile push notifications.
    - `read_at` string, date-time, nullable — Time when the message was marked as read. Only applicable for Inbox channel.
    - `unread_at` string, date-time, nullable — Time when a previously read message was marked unread. Only applicable for Inbox channel.
    - `archived_at` string, date-time, nullable — Time when the message was archived. Only applicable for Inbox channel.
    - `unarchived_at` string, date-time, nullable — Time when a previously archived message was unarchived. Only applicable for Inbox channel.
    - `is_read` boolean — Whether the message is currently in the read state. Only applicable for Inbox channel.
    - `is_archived` boolean — Whether the message is currently archived. Only applicable for Inbox channel.
    - `status` 'triggered' | 'trigger_failed' | 'trigger_blocked' | 'not_to_be_triggered' | 'to_be_triggered' | 'sent_by_vendor' | 'delivered' | 'delivery_failure' | 'seen' | 'clicked' | 'dismissed' | 'read' — Current message status. Other than `archived`, all actions translate to a status. Archived is just a flag on the message. - `triggered` - Message has been triggered by SuprSend and queued for delivery to the vendor. - `trigger_failed` - Vendor reported failure in response to delivery API call itself. - `trigger_blocked` - Test mode is enabled and this channel was not part of allowed channel list. - `not_to_be_triggered` - Message was intentionally skipped (generally happens in smart delivery when success metric is achieved) - `to_be_triggered` - Message is queued and waiting to be triggered (generally happens when there is a wait added in smart delivery) - `sent_by_vendor` - Vendor accepted the message for delivery; final delivery confirmation is pending. - `delivered` - Vendor confirmed successful delivery to the recipient. - `delivery_failure` - Vendor reported a delivery failure (for example, bounce or invalid recipient). - `seen` - Recipient saw or opened the message. - `clicked` - Recipient clicked or interacted with the message. - `dismissed` - Recipient dismissed the message without acting on it. - `read` - Inbox message was marked as read by the recipient.
    - `channel` 'sms' | 'email' | 'whatsapp' | 'inbox' | 'androidpush' | 'iospush' | 'webpush' | 'slack' | 'ms_teams' — Channel through which the message was sent.
    - `idempotency_key` string — Idempotency key supplied at trigger time to prevent duplicate sends for the same logical event.
    - `failure_reason` string — Human-readable reason describing why delivery failed. Empty when the message did not fail.
    - `recipient` object — Recipient of the message. Either a user (`$type: user`) or an object (`$type: object`).
      - `$type` 'user' | 'object' — Recipient type - `user` for a user recipient or `object` for an object recipient.
      - `distinct_id` string — Distinct ID of the user recipient. Present when `$type` is `user`.
      - `object_type` string — Object type slug. Present when `$type` is `object`.
      - `id` string — Object ID. Present when `$type` is `object`.
    - `parent_entity_id` string — ID of the parent entity (object)
    - `parent_entity_type` string — Type of the parent entity that originated this message (object)
    - `vendor` object — Delivery vendor that handled this message.
      - `name` string — Internal name of the vendor integration (for example, `sendgrid`, `twilio`).
      - `nickname` string — User-defined nickname for the vendor integration in the SuprSend dashboard.
    - `execution_id` string — ID of the workflow execution this message belongs to.
    - `parent_execution_id` string — ID of the parent execution, when this message was produced as fanout on object trigger.
    - `is_campaign` boolean — true when message was sent as part of a broadcast.
    - `tenant_id` string — ID of the tenant the message was sent under.
    - `workflow` object — Workflow that produced the message.
      - `slug` string — Unique slug of the workflow.
      - `version_id` string — ID of the specific workflow version that ran.
      - `name` string — Human-readable name of the workflow.
      - `node_ref` string — Slug to the specific node within the workflow that emitted this message.
    - `template` object — Template used to render the message.
      - `name` string — Human-readable name of the template.
      - `slug` string — Unique slug of the template.
      - `version_no` integer — Version number of the template that was used to render the message.
      - `variant_id` string — ID of the template variant used to render the message. `default` for the base variant.
    - `content` object — Rendered message content. Only present when `include_content=true` is passed as a query parameter.
    - `channel_identity` object — Channel-specific recipient identity that the message was delivered to (for example, the phone number for SMS, email address for email). Credential keys (`access_token`, `keys`, `incoming_webhook`) are stripped from the response.
    - `category` string — Notification category slug associated with this message.

---

[API](https://skmtc.net/suprsend/apis/suprsend-api.md) · [All operations](https://skmtc.net/suprsend/apis/suprsend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/suprsend/suprsend-api/versions/8bd2574bd2c3/schema)