List Messages

Retrieve messages and check delivery status.

List All Messages

curl https://api.textbubbles.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	50	Results per page (1-100)
`cursor`	string	No	—	Pagination cursor from previous response
`status`	string	No	—	Filter by status: `queued`, `pending`, `sent`, `delivered`, `read`, `failed`, `unsent`, `scheduled`
`to`	string	No	—	Filter by recipient (E.164 format)

Response:

{
  "success": true,
  "data": {
    "messages": [],
    "pagination": {
      "hasMore": true,
      "nextCursor": "eyJ..."
    }
  },
  "requestId": "req_abc123"
}

Pass pagination.nextCursor as the cursor parameter to fetch the next page.

Get Message Status

curl https://api.textbubbles.com/v1/messages/msg_550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": "msg_550e8400-e29b-41d4-a716-446655440000",
    "status": "delivered",
    "to": "+14155551234",
    "from": "+19876543210",
    "channel": "imessage",
    "content": {
      "text": "Hello from TextBubbles!"
    },
    "timeline": [
      { "status": "queued", "at": "2026-03-28T10:00:00Z", "channel": null },
      { "status": "sent", "at": "2026-03-28T10:00:01Z", "channel": "imessage" },
      { "status": "delivered", "at": "2026-03-28T10:00:03Z", "channel": "imessage" }
    ],
    "fallbackTriggered": false,
    "metadata": null,
    "externalId": "external-guid-123",
    "errorCode": null,
    "errorMessage": null,
    "createdAt": "2026-03-28T10:00:00Z"
  },
  "requestId": "req_abc123"
}

Inbound Messages

Inbound messages are delivered via the message.inbound webhook event. To receive them, subscribe to message.inbound in your webhook configuration.

Verification / OTP messages are suppressed

Inbound messages detected as one-time passcodes, 2FA codes, password-reset codes, or other verification codes (e.g. Apple ID, Google, bank account codes) are not surfaced through the API. They are:

not dispatched as message.inbound webhooks,
not delivered via the /v1/events stream,
not returned by GET /v1/messages

Message Statuses

Status	Description
`queued`	Message accepted, waiting for delivery
`pending`	Being processed for delivery
`scheduled`	Queued for future delivery
`sent`	Sent to the carrier/provider
`delivered`	Confirmed delivered to recipient
`read`	Read receipt received (iMessage only)
`failed`	Delivery failed
`unsent`	Message was unsent/retracted

Endpoints

Method	Path	Description
`GET`	`/v1/messages`	List messages (including inbound)
`GET`	`/v1/messages/:id`	Get message status
`DELETE`	`/v1/messages/:id`	Soft-delete a message

Send Messages Scheduled Messages