Texts

List, search, and manage SMS and MMS text messages for your phone numbers, and send outbound SMS. MMS messages include media attachments returned as presigned URLs.

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 SMS from one of your phone numbers. The message starts in delivery_status: "queued"; final delivery state is reported via webhook.

Preconditions

• Local numbers only. Only local (10-digit) numbers can send SMS today — toll-free numbers are receive-only.
• Sender warm-up. When you provision a new local number, the underlying 10DLC campaign takes around 10–15 minutes to register downstream. The number's sms_status field reports "pending" while that's in flight; calls to send during that window return 409 with error sender_sms_pending. Once sms_status becomes "ready", the number is ready to send.
• Recipient opt-in. Recipients have to opt in before you can text them: they send START to any number in your organization. Sending to a recipient who hasn't opted in returns 403 with error recipient_not_opted_in. If they later send STOP, future sends to them return 403 recipient_opted_out. Sending to another active phone number that lives in the same organization is allowed without an explicit opt-in.
• Contact rules configured on the sending number still apply on top of the consent check.

Rate limits

A phone number on Inkbox's default 10DLC campaign can send at most 20 outbound SMS per rolling 24-hour window. Registering your own brand and campaign lifts this cap to the carrier-assigned tier — see 10DLC registration for the full setup. Every send response — both success and failure — includes the standard rate-limit headers so you can pace your traffic:

Request body

Request example

JSON

Response (201)

JSON

Error responses

GET /numbers/{phone_number_id}/texts

List text messages for a phone number, newest first. Excludes deleted 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)

JSON

MMS messages have type: "mms" and a media array. Each media item includes a content_type, size in bytes, and a presigned url that expires after 1 hour.

Error responses

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

Update a text message. Use this to mark messages as read or to delete them.

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 and exclude deleted messages.

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 — one row per remote phone number, ordered by most recent message, with the latest message preview and unread count.

Query parameters

With is_blocked=false, latest previews, ordering, unread counts, and totals are computed from non-blocked rows only, so blocked-only counterparties drop out. Identity-scoped API keys never see blocked rows in conversation summaries.

Response (200)

JSON

Error responses

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

Get all messages exchanged with a specific remote number, newest first. The remote_number can be an E.164 phone number (for example +15167251294) or a short code (for example 76934).

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/{remote_number}

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

Path parameters

Request body

Request example

JSON

Response (200)

JSON

Returns updated_count: 0 when no messages needed updating. That is not an error.

Error responses