Messages
List outbound messages
Returns your organization's outbound messages, newest first, with cursor pagination.
This endpoint returns the next-page token in the X-Next-Cursor response
header rather than in meta.next_cursor. Read that header to page forward.
Requires the messages:read scope.
AuthorizationBearer <token>
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Query Parameters
cursor?string
limit?integer
Default
50Range
1 <= value <= 200status?string
Value in
"queued" | "sending" | "sent" | "delivered" | "failed" | "undelivered"from?string
to?string
tag?string
Length
length <= 64Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/messages"{
"success": true,
"data": [
{
"id": "8f3a2b1c-1c2d-4e5f-9a8b-0c1d2e3f4a5b",
"from": "+15551112222",
"to": "+15554443333",
"text": "hello from agentmessage",
"channel": "sms",
"priority": "default",
"status": "delivered",
"bandwidth_message_id": "bw-1700000000-abc",
"segment_count": 1,
"tag": "order-7421",
"created_at": "2026-04-26T12:00:00Z",
"sent_at": "2026-04-26T12:00:00.250Z",
"delivered_at": "2026-04-26T12:00:01.420Z"
}
],
"meta": {
"total": 0,
"limit": 50,
"offset": 0,
"next_cursor": null
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}