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,
        "variant_id": "default"
      },
      "content": {
        "header": "Your order #5678 is confirmed",
        "body": "Hi Alex, we've received your order #5678. We'll notify you once it ships.",
        "schema_version": "1.0",
        "templating_language": "handlebars"
      },
      "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,
        "variant_id": "default"
      },
      "content": {
        "body": "Your password reset code is 482913. It expires in 10 minutes.",
        "schema_version": "1.0",
        "templating_language": "handlebars"
      },
      "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 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).

​
before
string

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[]
enum<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.

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). 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_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 ID.

​
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.

​
include_content
boolean
default:false

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

200 - application/json

Returns the paginated list of messages order by created_at desc.

​
meta
object
​
results
object[]