Texts

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

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

Beta group MMS uses the same endpoint:

JSON

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.

JSON

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. Every recipient must opt in before you can text them. Sending to a recipient who has not opted in returns 403 recipient_not_opted_in; sending to a recipient who later sent STOP 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:

Request body

Response (201)

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

JSON

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

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

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

GET /numbers/{phone_number_id}/texts

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

Query parameters

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.

Response (200)

JSON

Error responses

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

Get a single text message by ID.

Path parameters

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

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

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

Path parameters

Request body

Request example

JSON

Response (200)

Returns the updated TextMessage object.

Error responses

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

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

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

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.

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

Error responses

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

Query parameters

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

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

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

Path parameters

Request body

Request example

JSON

Response (200)

JSON

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

recipients[] is only present on outbound text messages.