Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

List messages

Returns a paginated list of the authenticated user's messages — outbound and inbound merged into a single feed. Each message includes a durable message_handle that can be passed to /get-message-api/:message_handle for the full record.

GET/get-messages-apiBearer token

Query parameters

limitinteger (1–100)
Maximum number of messages to return. Defaults to 100.
offsetinteger (≥ 0)
Pagination offset. Defaults to 0. offset + limit must be ≤ 2000; deeper pages return 400 regardless of limit.
order_by"createdAt" | "sentAt"
Sort field. Defaults to createdAt.
order_direction"asc" | "desc"
Sort direction. Defaults to desc (newest first).
service"iMessage" | "SMS" | "RCS"
Filter by delivery service. Note: RCS is inbound-only — combining service=RCS with direction=outbound returns zero results.
direction"inbound" | "outbound"
Filter to inbound or outbound only. Omit for both.
pb_line_idstring
Encoded Project Blue line id (from GET /get-lines). The only supported way to filter by one of your own PB lines — do not use from_number/to_number for that.
from_numberstring (E.164)
External sender. Inbound-only filter. Combining with direction=outbound returns 400.
to_numberstring (E.164)
External recipient. Outbound-only filter. Combining with direction=inbound returns 400.
created_at_gtestring (ISO-8601)
Lower bound on created_at.
created_at_ltestring (ISO-8601)
Upper bound on created_at.
sent_at_gtestring (ISO-8601)
Lower bound on sent_at.
sent_at_ltestring (ISO-8601)
Upper bound on sent_at.
Group messages and from_number / to_number

On outbound group messages, to_number is the group's chat identifier (chat…), not an E.164 number. On inbound group messages, from_number is the individual participant who replied. The to_number and from_number filters are therefore not a way to fetch a group thread.

There is currently no supported filter for reading one group thread from /get-messages-api. The pbg_ groupId is not accepted as a filter, and the chat identifier is not exposed as a queryable field on this API.

About message_handle
The message_handle is an opaque, user-scoped identifier. Don't try to parse or decode it — just hand it back to /get-message-api to look up that specific message.
API reference