Texts - Inkbox

List, search, and manage SMS/MMS text messages for your phone numbers. The text API is conversation-centric: 1:1 SMS/MMS and beta group MMS use the same endpoints and response objects. All text endpoints are scoped to a phone number: /numbers/{phone_number_id}/texts/...

Path parameters

Parameter	Type	Description
`phone_number_id`	UUID	Unique identifier of the phone number

Send text

Send Idempotency-Key with Prefer: idempotency-replay to protect retries. Repeating the same key and input returns the original response, not a second text. SDKs generate a key for each send call; use an explicit key across separate calls. A queued message is accepted for delivery; request retries do not guarantee delivery retries. Use message reads or webhooks for current delivery status. See message send retries.

POST /numbers/{phone_number_id}/texts

Send an outbound message from one of your phone numbers. Pass to as a string for 1:1 SMS/MMS, as a list of 1-8 E.164 numbers for a conversation send, or pass conversation_id to reply into an existing conversation. Lists with 2 or more resolved recipients are sent as beta group MMS. Beta: Group MMS and conversation sends are beta. Some carriers may reject group chats or MMS from 10DLC numbers even when the sender is ready and recipients have opted in. The legacy 1:1 request shape still works unchanged:

JSON

{
  "to": "+15551234567",
  "text": "Hi from your agent."
}

Beta group MMS uses the same endpoint:

JSON

{
  "to": ["+15551234567", "+12125550199"],
  "text": "The appointment moved to 3:30.",
  "media_urls": ["https://example.com/updated-calendar.png"]
}

To reply into an existing conversation, pass conversation_id instead of to. The server resolves the conversation to its participants and applies the same 1:1 or group routing based on recipient count. Companion group replies require this canonical conversation_id; raw recipients cannot borrow sponsorship. MMS chats with the same participants and local number share a conversation identity. Readable Companion history does not imply send consent. Inspect reply readiness, preserve every participant, and handle the existing opt-in, opt-out, and sender-readiness errors.

JSON

{
  "conversation_id": "e0bc45d2-7478-4b3b-9b7c-cfc73f1ba201",
  "text": "Following up in the same conversation."
}

Preconditions

Sender warm-up. A newly provisioned local number can take around 10-15 minutes for its 10DLC campaign to register downstream. While sms_status is "pending", sends return 409 sender_sms_pending.
Recipient opt-in (US). Recipients in the US and US territories (Puerto Rico, US Virgin Islands, Guam, American Samoa, and Northern Mariana Islands) must opt in before you can text them. Sending to one of these recipients without an opt-in returns 403 recipient_not_opted_in. Recipients in other countries, including Canada and other non-US +1 countries such as the Bahamas and Jamaica, don’t need a prior opt-in. You’re responsible for having consent to text Canadian recipients under Canada’s Anti-Spam Legislation (CASL). Inkbox treats a number it can’t map to a country as US and requires an opt-in.
Recipient opt-out. A recipient who sent STOP can’t be texted from any country. Sending to them returns 403 recipient_opted_out.
Contact rules. Rules configured on the sending number still apply. Multi-recipient sends are all-or-nothing: one blocked or non-opted-in recipient rejects the request.
Group destination region. Group MMS recipients must be US or Canadian E.164 numbers.
Beta carrier behavior. Group MMS and MMS over 10DLC are still carrier-dependent; some carriers may reject group chats or MMS from 10DLC numbers.

Rate limits

A phone number on Inkbox’s default 10DLC campaign can send to at most 100 recipients per rolling 24-hour window. A 3-recipient group message counts as 3 recipient sends. Registering your own brand and campaign lifts this cap to the carrier-assigned tier; see 10DLC registration. When the cap is reached, 429 responses include:

Header	Description
`X-RateLimit-Limit`	Maximum recipient sends allowed per number per 24 hours (`100` on the default campaign)
`X-RateLimit-Remaining`	Remaining recipient sends in the current window
`X-RateLimit-Reset`	ISO 8601 timestamp at which the oldest send in the window will fall off
`Retry-After`	Seconds until at least one slot frees up

Request body

Field	Type	Required	Description
`to`	string \| string[]	Conditional	One E.164 destination for 1:1, or a list of 1-8 E.164 destinations. Lists with 2 or more recipients send beta group MMS. Mutually exclusive with `conversation_id`
`conversation_id`	UUID \| null	Conditional	Existing conversation to reply into. The server resolves it to the conversation participants. Mutually exclusive with `to`
`text`	string \| null	No	Message body, up to 1600 characters. Required unless `media_urls` has at least one item
`media_urls`	string[] \| null	No	Publicly fetchable media URLs to attach, up to 10 entries. Required unless `text` is present

Response (201)

1:1 responses keep the legacy fields populated and add conversation-aware fields:

JSON

{
  "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "direction": "outbound",
  "local_phone_number": "+14155550100",
  "remote_phone_number": "+15551234567",
  "text": "Hi from your agent.",
  "type": "sms",
  "media": null,
  "is_read": true,
  "delivery_status": "queued",
  "origin": "user_initiated",
  "error_code": null,
  "error_detail": null,
  "sent_at": null,
  "delivered_at": null,
  "failed_at": null,
  "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
  "sender_phone_number": null,
  "recipients": [
    {
      "recipient_phone_number": "+15551234567",
      "delivery_status": "queued",
      "carrier": null,
      "line_type": null,
      "error_code": null,
      "error_detail": null,
      "sent_at": null,
      "delivered_at": null,
      "failed_at": null
    }
  ],
  "is_blocked": false,
  "created_at": "2026-04-26T14:30:00Z",
  "updated_at": "2026-04-26T14:30:00Z"
}

Group responses keep the same object shape. remote_phone_number and legacy timestamp/error fields are null; use conversation_id, the message-level delivery_status rollup, and recipients[].

JSON

{
  "id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
  "direction": "outbound",
  "local_phone_number": "+14155550100",
  "remote_phone_number": null,
  "text": "The appointment moved to 3:30.",
  "type": "mms",
  "media": [
    {
      "content_type": "image/png",
      "size": 84321,
      "url": "https://example.com/updated-calendar.png"
    }
  ],
  "is_read": true,
  "delivery_status": "queued",
  "origin": "user_initiated",
  "error_code": null,
  "error_detail": null,
  "sent_at": null,
  "delivered_at": null,
  "failed_at": null,
  "conversation_id": "e0bc45d2-7478-4b3b-9b7c-cfc73f1ba201",
  "sender_phone_number": null,
  "recipients": [
    {
      "recipient_phone_number": "+15551234567",
      "delivery_status": "queued",
      "carrier": null,
      "line_type": null,
      "error_code": null,
      "error_detail": null,
      "sent_at": null,
      "delivered_at": null,
      "failed_at": null
    },
    {
      "recipient_phone_number": "+12125550199",
      "delivery_status": "queued",
      "carrier": null,
      "line_type": null,
      "error_code": null,
      "error_detail": null,
      "sent_at": null,
      "delivered_at": null,
      "failed_at": null
    }
  ],
  "is_blocked": false,
  "created_at": "2026-04-26T14:30:00Z",
  "updated_at": "2026-04-26T14:30:00Z"
}

Group outbound — remote_phone_number is null (no single remote party), top-level delivery_status is the message-level rollup, legacy timestamp/error fields stay null, and recipients carries one entry per addressee:

JSON

{
  "id": "9d4c2e0b-4a18-49a3-bd61-ea6e9d7c8910",
  "direction": "outbound",
  "local_phone_number": "+14155550100",
  "remote_phone_number": null,
  "text": "Heads up — meeting moved to 3pm",
  "type": "mms",
  "media": null,
  "is_read": true,
  "delivery_status": "queued",
  "origin": "user_initiated",
  "error_code": null,
  "error_detail": null,
  "sent_at": null,
  "delivered_at": null,
  "failed_at": null,
  "conversation_id": "8b1d2f3c-9012-4abc-9c1f-3211ee44aabb",
  "sender_phone_number": null,
  "recipients": [
      {
          "recipient_phone_number": "+14155550999",
          "delivery_status": "queued",
          "carrier": null, "line_type": null,
          "error_code": null, "error_detail": null,
          "sent_at": null, "delivered_at": null, "failed_at": null
      },
      {
          "recipient_phone_number": "+14155550211",
          "delivery_status": "queued",
          "carrier": null, "line_type": null,
          "error_code": null, "error_detail": null,
          "sent_at": null, "delivered_at": null, "failed_at": null
      },
      {
          "recipient_phone_number": "+14155550342",
          "delivery_status": "queued",
          "carrier": null, "line_type": null,
          "error_code": null, "error_detail": null,
          "sent_at": null, "delivered_at": null, "failed_at": null
      }
  ],
  "is_blocked": false,
  "created_at": "2026-04-26T14:30:00Z",
  "updated_at": "2026-04-26T14:30:00Z"
}

The final delivery state of every leg is reported asynchronously through text.* webhooks. For group sends, lifecycle events fire once per recipient with data.recipient_phone_number identifying the leg.

Error responses

Status	Description
400	Phone number not active
403	`recipient_not_opted_in` - one or more US or US territory recipients have not texted `START` to a number in your organization
403	`recipient_opted_out` - one or more recipients texted `STOP` and can no longer be messaged
403	Send blocked by a contact rule on the sending number
404	Phone number or `conversation_id` not found
409	`sender_sms_pending` - local number’s 10DLC registration is still propagating
409	Sending number is not eligible to send SMS/MMS
422	Invalid request body, no text/media content, both/neither `to` and `conversation_id`, duplicate recipients, too many recipients, or unsupported group destination
422	`message_blocked_spam_filter` - the message was rejected for policy reasons before carrier handoff. The attempt is stored with `delivery_status: "blocked_spam_filter"` (see the text message object) and no delivery lifecycle webhooks fire for it; the error’s `message` explains what to change before resending
429	24-hour recipient-send limit reached on this number; respect the `Retry-After` header

List texts

GET /numbers/{phone_number_id}/texts

List text messages for a phone number, newest first. Group messages appear alongside 1:1 messages.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of results (1-200)
`offset`	integer	0	Pagination offset
`is_read`	boolean	-	Filter by read state. Omit for all messages
`is_blocked`	boolean	-	Filter by blocked state. `true` returns only blocked rows, `false` returns only non-blocked rows, and omitting it applies the caller’s default visibility
`start_datetime`	string	-	Only texts created on or after this date/time
`end_datetime`	string	-	Only texts created on or before this date/time; a bare date includes the whole day
`tz`	string	UTC	IANA zone for interpreting zone-less `start_datetime`/`end_datetime` values. Defaults to UTC

Identity-scoped API keys never see contact-rule-blocked texts, regardless of is_blocked. Admin API keys and human sessions see blocked and non-blocked texts by default; use is_blocked=true for an admin-side blocked listing. start_datetime, end_datetime, and tz filter on created_at. Both bounds are optional and non-breaking — omit them for unchanged behavior. See Filtering by date.

Response (200)

JSON

[
  {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "direction": "inbound",
    "local_phone_number": "+14155550100",
    "remote_phone_number": "+12125550199",
    "text": "Hey, when is my order arriving?",
    "type": "sms",
    "media": null,
    "is_read": false,
    "delivery_status": null,
    "origin": "user_initiated",
    "error_code": null,
    "error_detail": null,
    "sent_at": null,
    "delivered_at": null,
    "failed_at": null,
    "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
    "sender_phone_number": "+12125550199",
    "recipients": null,
    "is_blocked": false,
    "created_at": "2026-03-10T14:30:00Z",
    "updated_at": "2026-03-10T14:30:00Z"
  }
]

Error responses

Status	Description
403	Phone number belongs to a different organization
404	Phone number not found
422	Validation failed: missing both `text` and `media_urls`, `to` list outside 1–8 recipients, group send to a non-US/CA number, `media_urls` longer than 10, or `text` longer than 1600 characters

Get text

GET /numbers/{phone_number_id}/texts/{text_id}

Get a single text message by ID.

Path parameters

Parameter	Type	Description
`text_id`	UUID	Unique identifier of the text message

Response (200)

Returns a TextMessage object. MMS messages have type: "mms" and a media array. Each media item includes a content_type, size in bytes, and a URL. URLs returned for stored inbound MMS media are presigned and expire after 1 hour.

Error responses

Status	Description
404	Text not found, wrong phone number, or wrong organization

Update text

PATCH /numbers/{phone_number_id}/texts/{text_id}

Update a text message, for example to mark it as read.

Path parameters

Parameter	Type	Description
`text_id`	UUID	Unique identifier of the text message

Request body

Field	Type	Required	Description
`is_read`	boolean	No	Mark as read (`true`) or unread (`false`)

Request example

JSON

{
  "is_read": true
}

Response (200)

Returns the updated TextMessage object.

Error responses

Status	Description
404	Text not found, wrong phone number, or wrong organization

Search texts

GET /numbers/{phone_number_id}/texts/search

Full-text search across text message bodies for a phone number. Results are ranked by relevance.

Query parameters

Parameter	Type	Default	Description
`q`	string	-	Search query (required, 1-500 characters)
`limit`	integer	50	Number of results (1-200)
`is_blocked`	boolean	-	Filter by blocked state. `true` searches only blocked rows, `false` searches only non-blocked rows, and omitting it applies the caller’s default visibility

Identity-scoped API keys never see contact-rule-blocked texts in search results. Admin API keys and human sessions see everything by default; pass is_blocked=false to exclude blocked spam from search results or is_blocked=true to search only blocked rows.

Response (200)

Returns a list[TextMessage] matching the query.

Error responses

Status	Description
403	Phone number belongs to a different organization
404	Phone number not found
422	Missing or invalid `q` parameter

List conversations

GET /numbers/{phone_number_id}/texts/conversations

List conversation summaries ordered by most recent message, with latest-message preview and unread count. By default this endpoint returns only 1:1 conversations so existing clients keep the same sidebar behavior. Pass include_groups=true to include group conversations.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of results (1-200)
`offset`	integer	0	Pagination offset
`include_groups`	boolean	false	Include group conversations in the listing
`is_blocked`	boolean	-	Filter by blocked state of messages. `true` summarizes blocked rows only, `false` summarizes non-blocked rows only, and omitting it applies the caller’s default visibility
`start_datetime`	string	-	Only conversations created on or after this date/time
`end_datetime`	string	-	Only conversations created on or before this date/time; a bare date includes the whole day
`tz`	string	UTC	IANA zone for interpreting zone-less `start_datetime`/`end_datetime` values. Defaults to UTC

With is_blocked=false, latest previews, ordering, unread counts, and totals are computed from non-blocked rows only, so blocked-only conversations drop out. Identity-scoped API keys never see blocked rows in conversation summaries. start_datetime, end_datetime, and tz filter on the conversation’s created_at — when the conversation was created, not its latest-message time. This list is ordered by most recent message, but the date filter is on creation time. Previews, unread counts, totals, and ordering still describe the full conversation — they are not sliced to the window. Both bounds are optional and non-breaking — omit them for unchanged behavior. See Filtering by date.

Response (200)

Each row carries the conversation’s id, the participant list, and an is_group flag. For 1:1 rows, remote_phone_number is the single participant; for group rows it’s null (the participant set is the source of truth). latest_has_media is the reliable signal that the latest message carried media — derived from the message’s media column, since carriers tag many text-only messages as MMS at the wire.

JSON

[
  {
    "remote_phone_number": "+12125550199",
    "id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
    "participants": ["+12125550199"],
    "is_group": false,
    "latest_text": "Hey, when is my order arriving?",
    "latest_direction": "inbound",
    "latest_type": "sms",
    "latest_has_media": false,
    "latest_message_at": "2026-03-10T14:30:00Z",
    "unread_count": 2,
    "total_count": 15
  },
  {
    "remote_phone_number": null,
    "id": "e0bc45d2-7478-4b3b-9b7c-cfc73f1ba201",
    "participants": ["+15551234567", "+12125550199"],
    "is_group": true,
    "latest_text": "The appointment moved to 3:30.",
    "latest_direction": "outbound",
    "latest_type": "mms",
    "latest_has_media": true,
    "latest_message_at": "2026-04-26T14:30:00Z",
    "unread_count": 0,
    "total_count": 3
  }
]

Error responses

Status	Description
403	Phone number belongs to a different organization
404	Phone number not found

Get conversation

GET /numbers/{phone_number_id}/texts/conversations/{key}

Get all messages in a conversation, newest first. {key} accepts the conversation UUID for any conversation. For 1:1 threads, the key can also be the remote phone number, short code, or sender ID. Group conversations must be addressed by UUID. Use the id from the conversation summary or conversation_id from any message in the group.

Path parameters

Parameter	Type	Description
`key`	string	Conversation UUID, or a 1:1 remote phone number / short code / sender ID

Query parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of results (1-200)
`offset`	integer	0	Pagination offset

Identity-scoped API keys see only non-blocked rows in the thread. Admin API keys and human sessions see blocked and non-blocked rows merged inline, with each row tagged by is_blocked.

Response (200)

Returns a list[TextMessage] for the conversation.

Error responses

Status	Description
400	Conversation key is malformed (not a UUID and not a recognized phone number)
403	Phone number belongs to a different organization
404	Phone number not found, or no conversation matches the key on this phone number

Update conversation

PATCH /numbers/{phone_number_id}/texts/conversations/{key}

Bulk-update the read state for all non-blocked messages in a conversation.

Path parameters

Parameter	Type	Description
`key`	string	Conversation UUID, or a 1:1 remote phone number / short code / sender ID

Request body

Field	Type	Required	Description
`is_read`	boolean	Yes	Mark all messages as read (`true`) or unread (`false`)

Request example

JSON

{
  "is_read": true
}

Response (200)

JSON

{
  "remote_phone_number": null,
  "conversation_id": "e0bc45d2-7478-4b3b-9b7c-cfc73f1ba201",
  "is_read": true,
  "updated_count": 12
}

For 1:1 conversations, remote_phone_number is populated for legacy callers. For group conversations, it is null and conversation_id is the stable key. updated_count: 0 means no messages needed updating.

Error responses

Status	Description
400	Conversation key is malformed (not a UUID and not a recognized phone number)
403	Phone number belongs to a different organization
404	Phone number not found, or no conversation matches the key on this phone number
422	Missing or invalid `is_read`

Text message object

Field	Type	Description
`id`	string (UUID)	Message ID
`direction`	string	`"inbound"` or `"outbound"`
`local_phone_number`	string	Your Inkbox number (E.164)
`remote_phone_number`	string \| null	Legacy 1:1 remote party. Populated for 1:1 and inbound messages; `null` for outbound group messages
`text`	string \| null	Message body. Null for MMS-only messages
`type`	string	`"sms"` or `"mms"`. Group sends are always `"mms"`
`media`	array \| null	Media attachments (MMS only). Each item has `content_type`, `size`, and `url`
`is_read`	boolean	Whether the message has been read
`delivery_status`	string \| null	For outbound messages: `"queued"`, `"sent"`, `"delivered"`, `"delivery_failed"`, `"delivery_unconfirmed"`, `"sending_failed"`, or `"blocked_spam_filter"` (the send was rejected for policy reasons before carrier handoff and was not delivered). Null for inbound. On groups this is a rollup across `recipients[]` (the lowest lifecycle rank present; `"delivered"` is preferred at the terminal tier on mixed-outcome ties) — treat `recipients[].delivery_status` as authoritative per-leg
`origin`	string	How the message was created. `"user_initiated"` for messages sent via the API
`error_code`	string \| null	Legacy 1:1 delivery error code. Null for inbound and group messages; use `recipients[].error_code` for group
`error_detail`	string \| null	Legacy 1:1 delivery error detail. Null for inbound and group messages; use `recipients[].error_detail` for group
`sent_at`	string (ISO 8601) \| null	Legacy 1:1 handoff timestamp. Null for inbound and group messages; use `recipients[].sent_at` for group
`delivered_at`	string (ISO 8601) \| null	Legacy 1:1 confirmed-delivery timestamp. Null for inbound and group messages; use `recipients[].delivered_at` for group
`failed_at`	string (ISO 8601) \| null	Legacy 1:1 failure timestamp. Null for inbound and group messages; use `recipients[].failed_at` for group
`conversation_id`	string (UUID) \| null	Stable conversation key for 1:1 and group threads
`sender_phone_number`	string \| null	Sender for inbound messages. Null for outbound messages because the sender is `local_phone_number`
`recipients`	array \| null	Per-recipient delivery state for outbound messages. One entry for 1:1; 2-8 entries for group; null for inbound
`is_blocked`	boolean	Whether the message was rejected by a contact rule or by default-block in whitelist mode. Identity-scoped API keys never receive rows where this is `true`
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Recipient object

recipients[] is only present on outbound text messages.

Field	Type	Description
`recipient_phone_number`	string	Recipient phone number in E.164 format
`delivery_status`	string \| null	Per-recipient delivery status
`carrier`	string \| null	Carrier reported for the recipient, when available
`line_type`	string \| null	Carrier-reported line type, when available
`error_code`	string \| null	Carrier or Inkbox error code for this recipient
`error_detail`	string \| null	Human-readable detail accompanying `error_code`
`sent_at`	string (ISO 8601) \| null	When this recipient was handed off for delivery
`delivered_at`	string (ISO 8601) \| null	When delivery to this recipient was confirmed
`failed_at`	string (ISO 8601) \| null	When delivery to this recipient failed

Conversation summary object

Field	Type	Description
`remote_phone_number`	string \| null	Legacy 1:1 participant. Null for group conversations
`id`	string (UUID) \| null	Conversation UUID. Use this as the canonical key for group conversations
`participants`	string[] \| null	Remote participants in the conversation
`is_group`	boolean \| null	Whether the conversation has more than one remote participant
`latest_text`	string \| null	Latest message body preview
`latest_direction`	string	Direction of the latest message
`latest_type`	string	`"sms"` or `"mms"` for the latest message
`latest_has_media`	boolean	Whether the latest message actually has media attachments. This is separate from `latest_type` because group and carrier-routed messages can be `"mms"` without attachments
`latest_message_at`	string (ISO 8601)	Latest message timestamp
`unread_count`	integer	Unread message count in the summarized view
`total_count`	integer	Total message count in the summarized view

​Path parameters

​Send text

​Preconditions

​Rate limits

​Request body

​Response (201)

​Error responses

​List texts

​Query parameters

​Response (200)

​Error responses

​Get text

​Path parameters

​Response (200)

​Error responses

​Update text

​Path parameters

​Request body

​Request example

​Response (200)

​Error responses

​Search texts

​Query parameters

​Response (200)

​Error responses

​List conversations

​Query parameters

​Response (200)

​Error responses

​Get conversation

​Path parameters

​Query parameters

​Response (200)

​Error responses

​Update conversation

​Path parameters

​Request body

​Request example

​Response (200)

​Error responses

​Text message object

​Recipient object

​Conversation summary object

Path parameters

Send text

Preconditions

Rate limits

Request body

Response (201)

Error responses

List texts

Query parameters

Response (200)

Error responses

Get text

Path parameters

Response (200)

Error responses

Update text

Path parameters

Request body

Request example

Response (200)

Error responses

Search texts

Query parameters

Response (200)

Error responses

List conversations

Query parameters

Response (200)

Error responses

Get conversation

Path parameters

Query parameters

Response (200)

Error responses

Update conversation

Path parameters

Request body

Request example

Response (200)

Error responses

Text message object

Recipient object

Conversation summary object