gateway

List messages

Sent and received messages across your whole account, newest first, with delivery status on each. Filter by device, direction, status, text, and time range. Two pagination modes: page numbers for browsing, or cursor for polling. To poll for new messages: request order=asc with a from timestamp, follow nextCursor until hasMore is false, then resume from the last nextCursor on the next poll. Time filters apply to createdAt (when the platform stored the message). For received messages this is upload time, which can lag receivedAt if the device was offline. A received message uploaded more than 24 hours after receivedAt is stored with createdAt set to receivedAt and the upload time in originalCreatedAt, so a poll that has already moved past receivedAt does not return it.

get/api/v1/gateway/messages

Request

  • Base URL: https://api.textbee.dev
  • URL: https://api.textbee.dev/api/v1/gateway/messages
  • Auth: API key in header x-api-key

Query parameters

cursorstring

Opaque position from a previous response nextCursor. Returns the page after that position and switches meta to nextCursor/hasMore without a total count.

limitinteger

Messages per page. Default 50, maximum 100.

pageinteger

Page to return. Default 1. Mutually exclusive with cursor.

order'desc' | 'asc'

desc (default) for newest first; asc to walk forward in time when polling.

tostring

Exclusive upper bound on createdAt, same formats as from. Exclusive so consecutive windows never double-count a boundary message.

fromstring

Inclusive lower bound on createdAt, which for a received message uploaded more than 24 hours late equals receivedAt. ISO-8601 with an explicit timezone (2026-08-01T00:00:00Z or +03:00 form), or a date (2026-08-01, read as UTC midnight). A datetime without a timezone is rejected.

searchstring

Match against the message text and the other party number. Encrypted messages cannot be searched.

status'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received'

Delivery state to return. Combine with direction: direction=sent&status=failed lists sends that failed.

smsBatchIdstring

Only messages from this batch, using the smsBatchId returned by a send. Combine with status=failed to list the recipients of a batch that failed.

type'all' | 'sent' | 'received'

Deprecated alias of direction. Still works; prefer direction.

direction'all' | 'sent' | 'received'

Direction to return. Default all. Matches the lowercase direction field on each message. Not the same as status: direction=sent means outbound, status=sent means the device dispatched it.

deviceIdsstring

Comma-separated device ids to include, from GET /gateway/devices. Default: all devices on the account. Messages from deleted devices are never included.

Response

A page of messages.

Example response

{
  "data": [
    {
      "device": {
        "name": "Office phone",
        "brand": "google",
        "model": "Pixel 7"
      },
      "simUsed": {
        "subscriptionId": 19,
        "slotIndex": 1
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.