Skip to main content
GET
List messages

Authorizations

Authorization
string
header
required

Dashboard JWT token from Clerk

Headers

X-Test-Mode
enum<string>

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Available options:
true,
false

Query Parameters

cursor
string

Opaque cursor for the next page (from previous response meta.pagination.cursor)

limit
default:25

Number of items per page (default 25). Values above the page-size cap are silently clamped; negative, fractional, or unparseable values fall back to the default. Never 422s.

Required range: x >= 1
channel
string

Filter by channel

Maximum string length: 32
status
string

Filter by delivery status. Accepts every status the messages.status column can hold across all channels — DAG states (pending/queued/scheduled/accepted/sending/sent), terminal successes (delivered/submitted_no_receipt/read), failure modes (failed/rejected/undelivered/bounced/expired), and operational sentinels (suppressed/test_sent/deleted/unknown). Email spam complaints are not a distinct status — a complaint DLR is recorded as status=failed with metadata.complaint_type set to "spam_report". To isolate complaint-driven failures, filter on status=failed and inspect metadata.complaint_type. An empty or unknown value clears the filter.

Maximum string length: 36
to
string

Filter by recipient

Maximum string length: 100
direction
string

Filter by direction. Accepted values: inbound, outbound, internal. An empty or unknown value clears the filter.

Maximum string length: 32
contact_id
string

Filter by contact

Maximum string length: 100
dateRange
string

Date range filter (e.g. 7d, 30d, 90d)

Maximum string length: 10
from_date
string

Custom date range start. Accepts an ISO-8601 date (2026-05-25) or date-time (2026-05-25T00:00:00Z); any unparseable value is ignored (no date filter applied) rather than rejected.

Maximum string length: 40
to_date
string

Custom date range end. Accepts an ISO-8601 date (2026-05-25) or date-time (2026-05-25T23:59:59Z); any unparseable value is ignored (no date filter applied) rather than rejected.

Maximum string length: 40
conversation_id
string

Filter by conversation

Maximum string length: 100

Free-text inbox search across message content and participant addresses.

Maximum string length: 200
message_ids
string

Comma-separated list of message ids to look up directly (correlated cross-channel delivery log search). Each id is OR-matched against the internal id OR the provider-assigned external_id. Combine with the standard channel/from_date/to_date filters to narrow further.

Maximum string length: 4096
phone_number_id
string

Scope results to a single WhatsApp WABA by its phone_number_id (multi-WABA inbox filter).

Maximum string length: 64
groupBy
string

Group results. Accepted values: conversation, contact, channel. An empty or unknown value clears the grouping.

Maximum string length: 32

Response

Paginated list of messages

Paginated list of messages

data
object[]
meta
object