List message logs

GET/messages/smsAPI v1

GET /messages/sms returns a paginated list of per-message delivery records — the same DeliveryReceipt object returned by Send SMS and the message status endpoint — for the authenticated caller. Requests are authenticated with a Bearer token and scoped by your servicePlanId.

Authentication

Send your API token as Authorization: Bearer <token>. The required servicePlanId query parameter authorizes and scopes the search; only messages owned by the authenticated caller are returned.

Query parameters

servicePlanId is required. Provide at least one additional filter (from, to, status, country, mccmnc, fromDate, toDate, or cursor).

Parameter	Type	Required	Description
`servicePlanId`	`string (query)`	Yes	Service plan that owns the messages. Authorizes and scopes the search. 24-character hex identifier.
`from`	`string (query)`	No	Filter by sender address (short code, E.164 phone, or alphanumeric sender ID).
`to`	`string (query)`	No	Filter by destination address.
`status`	`string (query)`	No	Filter by public delivery status. Enum: QUEUED, SENT, DELIVERED, FAILED, UNKNOWN.
`country`	`string (query)`	No	Filter by ISO 3166-1 alpha-2 country code (for example US, PR).
`mccmnc`	`string (query)`	No	Filter by mobile country / network code. 5 or 6 digits.
`fromDate`	`string<date-time> (query)`	No	Start of the createdAt window (inclusive), ISO 8601 date-time. The window between fromDate and toDate may not exceed 31 days.
`toDate`	`string<date-time> (query)`	No	End of the createdAt window (inclusive), ISO 8601 date-time.
`limit`	`integer (query)`	No	Maximum number of items to return. Defaults to 20; capped at 100.
`cursor`	`string (query)`	No	Opaque pagination cursor from a previous response (pagination.nextCursor).

Pagination & sorting

Provide at least one filter in addition to servicePlanId: from, to, status, country, mccmnc, fromDate, toDate, or cursor.
Results are sorted newest-first by createdAt (ties broken by msgId).
The default page size is 20 and the maximum is 100; larger values are capped at 100.
When pagination.hasMore is true, pass pagination.nextCursor back as the cursor query parameter to fetch the next page.
Treat nextCursor as an opaque value: pass it back exactly as received, and do not construct or parse cursor values in client code.
When pagination.nextCursor is null, there are no further results.
An expired or malformed cursor is rejected with a 400 VALIDATION_ERROR; restart from the first page without a cursor.
The fromDate / toDate window filters on createdAt and may not exceed 31 days.

Responses

Status	Description
200	A paginated list of per-message delivery records, newest first.
400	Missing/malformed servicePlanId, invalid filter, invalid or too-large date range, or no filter provided in addition to servicePlanId.
401	Missing Bearer token, malformed Authorization header, or invalid token.
403	Token is valid but not authorized for the requested account/servicePlan mapping.
429	Rate limit exceeded. Retry after the indicated interval.
500	The message search failed (internal error).

Response envelope

The response is an object with an items array and a pagination object.

{
  "items": [
    {
      "accountId": "111111111111111111111111",
      "servicePlanId": "222222222222222222222222",
      "msgId": "019ee2da-e515-7322-805f-1ac6ce82f20f",
      "channel": "SMS",
      "direction": "MT",
      "from": "+15550001111",
      "to": "+15550002222",
      "body": "Your verification code is 123456",
      "status": "DELIVERED",
      "errorCode": "000",
      "errorMessage": "No error",
      "segments": 1,
      "price": 0.0007,
      "ptf": 0.0065,
      "currency": "USD",
      "mccmnc": "313790",
      "country": "PR",
      "createdAt": "2026-06-20T04:20:40.982Z",
      "sentAt": "2026-06-20T04:20:41.000Z",
      "updatedAt": "2026-06-20T04:20:41.087Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": null
  }
}

pagination

Field	Type	Description
`limit`	`integer`	Effective page size applied to this response (capped at 100).
`hasMore`	`boolean`	Whether more results are available beyond this page.
`nextCursor`	`string \| null`	Opaque cursor for the next page, or null when there are no further results. Pass it back as the cursor query parameter.

Item fields (DeliveryReceipt)

Each entry in items is the public delivery record (the delivery receipt).

Field	Type	Description
`accountId`	`string \| null`	Resolved account identifier (business partner) that owns the message.
`servicePlanId`	`string \| null`	Service plan that owns the message.
`msgId`	`string`	Server-generated message identifier (UUID).
`channel`	`string`	Message channel. Enum: SMS, MMS.
`direction`	`string`	Message direction (for example MT).
`from`	`string \| null`	Sender address.
`to`	`string \| null`	Destination address.
`body`	`string \| null`	SMS message text.
`status`	`string`	Simplified public delivery status. Enum: QUEUED, SENT, DELIVERED, FAILED, UNKNOWN.
`errorCode`	`string`	000 on success; otherwise the failure code.
`errorMessage`	`string`	Human-readable status/error message.
`segments`	`integer \| null`	Number of SMS segments.
`price`	`number \| null`	Charged price, when available.
`ptf`	`number \| null`	Pass-through fee, when available.
`currency`	`string \| null`	Currency of price/ptf.
`mccmnc`	`string \| null`	Mobile country/network code.
`country`	`string \| null`	ISO 3166 country code.
`createdAt`	`string<date-time>`	When the record was created.
`sentAt`	`string<date-time> \| null`	When the message was sent, when available.
`updatedAt`	`string<date-time>`	When the record was last updated.

Try it

Run GET /v1/messages/sms interactively with your own Bearer token in the SMS API Reference.