Skip to main content
GET
/
v1
/
message
List Messages
curl --request GET \
  --url https://hub.suprsend.com/v1/message \
  --header 'Authorization: Bearer <token>'
{
  "meta": {
    "count": 3506,
    "limit": 10,
    "has_prev": false,
    "before": null,
    "has_next": true,
    "after": "01HVXXXXXXXXXXXXXXXXXXXX10"
  },
  "results": [
    {
      "message_id": "01HVXXXXXXXXXXXXXXXXXXXX01",
      "created_at": "2026-04-01T17:18:06.000Z",
      "updated_at": "2026-04-01T17:20:11.000Z",
      "triggered_at": "2026-04-01T17:18:06.000Z",
      "delivered_at": "2026-04-01T17:18:08.000Z",
      "seen_at": "2026-04-01T17:19:25.000Z",
      "clicked_at": null,
      "dismissed_at": null,
      "read_at": null,
      "unread_at": null,
      "archived_at": null,
      "unarchived_at": null,
      "is_read": false,
      "is_archived": false,
      "status": "seen",
      "channel": "inbox",
      "idempotency_key": "order-5678",
      "failure_reason": null,
      "recipient": {
        "$type": "user",
        "distinct_id": "user_123",
        "object_type": null,
        "id": null
      },
      "parent_entity_id": null,
      "parent_entity_type": null,
      "vendor": {
        "name": "suprsend_inbox",
        "nickname": "Inbox"
      },
      "execution_id": "exec_01HV...",
      "parent_execution_id": null,
      "is_campaign": false,
      "tenant_id": "acme",
      "workflow": {
        "slug": "order-confirmation",
        "version_id": "wf_ver_01HV...",
        "name": "Order Confirmation",
        "node_ref": "send_inbox_1"
      },
      "template": {
        "name": "Order Confirmation",
        "slug": "order-confirmation",
        "version_no": 4
      },
      "channel_identity": {
        "inbox": "user_123"
      },
      "category": "transactional"
    },
    {
      "message_id": "01HVXXXXXXXXXXXXXXXXXXXX02",
      "created_at": "2026-04-01T17:30:01.000Z",
      "updated_at": "2026-04-01T17:30:15.000Z",
      "triggered_at": "2026-04-01T17:30:01.000Z",
      "delivered_at": null,
      "seen_at": null,
      "clicked_at": null,
      "dismissed_at": null,
      "read_at": null,
      "unread_at": null,
      "archived_at": null,
      "unarchived_at": null,
      "is_read": false,
      "is_archived": false,
      "status": "delivery_failure",
      "channel": "sms",
      "idempotency_key": null,
      "failure_reason": "invalid_recipient_number",
      "recipient": {
        "$type": "user",
        "distinct_id": "user_456",
        "object_type": null,
        "id": null
      },
      "parent_entity_id": null,
      "parent_entity_type": null,
      "vendor": {
        "name": "gupshup",
        "nickname": "Gupshup WhatsApp"
      },
      "execution_id": "exec_01HV...",
      "parent_execution_id": null,
      "is_campaign": false,
      "tenant_id": "acme",
      "workflow": {
        "slug": "password-reset",
        "version_id": "wf_ver_01HV...",
        "name": "Password Reset",
        "node_ref": "multichannel_1"
      },
      "template": {
        "name": "Password Reset",
        "slug": "password-reset",
        "version_no": 2
      },
      "channel_identity": {
        "sms": "+15555550100"
      },
      "category": "transactional"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Pass as Bearer <API_KEY>. Get API Key from SuprSend dashboard Developers -> API Keys section.

Query Parameters

​
limit
integer
default:10

Maximum number of messages to return per page. Defaults to 10, maximum is 1000.

Required range: x <= 1000
​
after
string

Cursor (message_id ULID) for forward pagination — returns the page of older messages after this ID. Takes precedence over before when both are set (before is silently ignored).

​
before
string

Cursor (message_id ULID) for backward pagination — returns the page of newer messages before this ID. Ignored when after is also set.

​
status
enum<string>[]

Filter by one or more derived statuses. Multiple values are OR-ed.

Available options:
triggered (status AnyOf('triggered','trigger_blocked','sent_by_vendor','to_be_triggered','not_to_be_triggered')),
delivery_failed (status AnyOf('trigger_failed','failure_by_vendor'),
delivered,
seen,
clicked,
dismissed,
read (is_read = true),
unread (is_read = false),
archived (is_archived = true)
​
channel
enum<string>

Filter by delivery channel.

Available options:
sms,
email,
androidpush,
iospush,
webpush,
inbox,
whatsapp,
slack,
ms_teams
​
recipient_id
string[]

Filter by one or more recipient distinct_ids (OR-ed).

​
category
string[]

Filter by one or more notification categories (OR-ed).

​
created_at_gte
string<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_lte
string<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_slug
string

Filter messages triggered from a specific workflow.

​
execution_id
string

Matches wf_exec_id or broadcast_id.

​
idempotency_key
string

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

​
message_id
string

Exact match on message ULID.

​
tenant_id
string

Filter messages belonging to a specific tenant.

​
is_campaign
boolean

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

​
object_id
string

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_type
string

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.

Response

200 - application/json

Returns the paginated list of messages order by created_at desc.

​
meta
object
​
results
object[]