iMessage API - Inkbox

API-first iMessage for AI agents. Use the shared Inkbox iMessage router or attach a dedicated line, then read and send messages, use tapbacks, read receipts, typing indicators, and media, and subscribe to events via webhooks. API base URL:

https://inkbox.ai/api/v1/imessage

Quick start

Create an account and get your API key from the Inkbox console:

Get API key

All API requests require authentication using an API key:

X-API-Key: YOUR_API_KEY

Things to know before your first call:

iMessage is opt-in per identity. Set imessage_enabled: true when creating or updating an identity.
Standard shared-service conversations start with the human. Recipients connect to a shared identity by texting connect @your-handle to the router number.
Organization-owned shared pools (Beta) are available only by request. Organizations with their own organization-owned shared iMessage pool can connect a recipient and submit an opening message without the router flow.
A dedicated line can start conversations. An identity with an attached dedicated line can start new 1:1 conversations and group chats with 2-8 E.164 recipients. Keep the returned conversation_id as the canonical group key. Group creation is asynchronous, and conversation reads report group_creation_status as creating, not_created, or ready. Existing lists exclude groups unless include_groups=true.

Dedicated lines

Dedicated lines belong to your organization and can be attached to an iMessage-enabled identity. Every dedicated line can start new 1:1 conversations and group chats. Shared service dynamically assigns a line only after someone connects to your agent. Dedicated lines can also receive 1:1 messages from non-phone sender addresses. Read these messages through the existing APIs and imessage.received webhooks. These conversations are receive-only; outbound recipients must still be E.164 phone numbers.

List dedicated lines

GET /numbers

Returns personal iMessage lines owned by your organization, including unattached lines. Shared-pool lines and routers are not included in this list.

Response (200)

JSON

[
  {
    "id": "3c34233a-c336-4ea6-8dc4-b5d26c996c47",
    "number": "+13105550123",
    "type": "dedicated_outbound",
    "line_role": "personal",
    "status": "active",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_handle": "sales-agent"
  }
]

Field	Type	Description
`id`	UUID	Dedicated-line identifier
`number`	string	iMessage number in E.164 format
`type`	string	Always `dedicated_outbound`. This response-only compatibility field is not a capability selector.
`line_role`	string	`personal`. Older responses may omit this additive field.
`status`	string	`active`; existing numbers may return `paused` as a read-only compatibility value. This field cannot be set through number or identity update requests.
`agent_identity_id`	UUID \| null	Attached identity ID, or `null` when unattached
`agent_handle`	string \| null	Attached identity handle, or `null` when unattached

bash

curl "https://inkbox.ai/api/v1/imessage/numbers" \
  -H "X-API-Key: YOUR_API_KEY"

Claim a dedicated line

POST /numbers

Claims one unattached dedicated line for the organization. Use an admin API key, or manage dedicated lines from the Inkbox Console. The request requires a stable key in the Idempotency-Key header:

Idempotency-Key: <unique stable key>

Request body

JSON

{}

Response (201)

Returns one unattached dedicated-line object with the same schema as the list endpoint. Its response-only type field remains "dedicated_outbound" for compatibility.

JSON

{
  "id": "3c34233a-c336-4ea6-8dc4-b5d26c996c47",
  "number": "+13105550123",
  "type": "dedicated_outbound",
  "line_role": "personal",
  "status": "active",
  "agent_identity_id": null,
  "agent_handle": null
}

Idempotency

Retry the same logical claim with the same key to receive its original result.
Reusing the key with different input returns 409.
Generate a new key only for a genuinely new claim.

bash

curl -X POST "https://inkbox.ai/api/v1/imessage/numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: claim-sales-line-01" \
  -H "Content-Type: application/json" \
  -d '{}'

Error responses

Status	Description
402	Your organization’s quota does not permit another dedicated line. Review billing in the Inkbox Console or contact support@inkbox.ai.
403	This operation requires an admin API key or the Inkbox Console.
409	The `Idempotency-Key` was already used with incompatible input. Use the original input, or use a new key for a genuinely new claim.
422	The request is invalid, including when `Idempotency-Key` is missing or the body contains unsupported input.
503	Inventory is temporarily unavailable. Honor `Retry-After`: retry after `5` seconds when another claim is in progress, or `3600` seconds when inventory is depleted. The depletion response says that a number is expected within 24 hours.

Attach or detach an organization-owned line through PATCH /api/v1/identities/{agent_handle}. Detaching does not release the line; there is no customer-facing line-release endpoint.

Router

Get router number

The active router number and the command humans text to connectGET /api/v1/imessage/triage-number

Messaging capability

Check messaging capability

Check whether a phone number is currently reachable over iMessage, SMS, or RCSGET /api/v1/imessage/check-messaging-capability

Messages

Send message

Send 1:1 or group iMessagesPOST /api/v1/imessage/messages

Get message

Read current delivery status, error fields, and reply relationshipsGET /api/v1/imessage/messages/{message_id}

Get a reply thread

Read the visible root and replies, oldest first, from any member messageGET /api/v1/imessage/messages/{message_id}/thread

List messages

List iMessages visible to the caller, newest firstGET /api/v1/imessage/messages

Upload media

Upload a file and get a URL usable in media_urlsPOST /api/v1/imessage/media

Dedicated-line group chats use these same message and conversation routes; there is no separate group-send endpoint.

Conversations

Connect a recipient

Available only by request for organizations with their own organization-owned shared iMessage poolPOST /api/v1/imessage/connect

Disconnect a recipient

Disconnect by agent identity and recipient phone numberPOST /api/v1/imessage/disconnect

List conversations

List conversation summaries with latest-message previews and unread countsGET /api/v1/imessage/conversations

Get conversation

Get a single conversation by IDGET /api/v1/imessage/conversations/{conversation_id}

Get conversation thread

Read one reply thread by its conversation and opaque thread IDGET /api/v1/imessage/conversations/{conversation_id}/threads/{thread_id}

List connections

List recipients currently connected to an agent identityGET /api/v1/imessage/assignments

Release connection

Disconnect a recipient from an agent identityDELETE /api/v1/imessage/assignments/{assignment_id}

Mark conversation read

Send a read receipt and mark inbound messages readPOST /api/v1/imessage/mark-read

Send typing indicator

Show the typing bubble to the conversation’s recipientPOST /api/v1/imessage/typing

Tapbacks

Send tapback

React to a message; a new tapback replaces your previous onePOST /api/v1/imessage/reactions

Remove tapback

Take back a tapback your agent sentDELETE /api/v1/imessage/reactions/{reaction_id}

Contact rules

Per-identity allow and block entries share one phone policy for SMS/MMS, calls, and iMessage. imessage_filter_mode and phone_filter_mode set both defaults (blacklist initially); canonical phone_inbound_filter_mode and phone_outbound_filter_mode customize each direction. Rules cover inbound, outbound, or both (the create default). Shared-line connection setup requires both effective permissions without granting them; dedicated-line traffic checks its own direction. See the Contact rules reference and the iMessage guide.

List contact rules

List allow/block rules for an agent identityGET /api/v1/imessage/identities/{agent_handle}/contact-rules

Create contact rule

Add an allow or block rule (E.164 exact match)POST /api/v1/imessage/identities/{agent_handle}/contact-rules

Get contact rule

Fetch a single rule by IDGET /api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}

Update contact rule

Change a rule’s action (admin-only)PATCH /api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}

Delete contact rule

Delete a rule (admin-only)DELETE /api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}

List org iMessage contact rules

Org-wide aggregate list across every identity (admin-only)GET /api/v1/imessage/contact-rules

Webhooks

Inbound events (imessage.received, imessage.reaction_received) and outbound delivery-lifecycle events (imessage.sent, imessage.delivered, imessage.delivery_failed) are delivered via the Webhook Subscriptions API — attach a subscription to the agent identity with the subset you want. See the iMessage webhooks reference for event types, payload format, and signature verification.

Filtering by date

Date filtering applies to two list endpoints — List messages (GET /messages) and List conversations (GET /conversations). These accept three optional query parameters that filter results by when each record was created (created_at, stored in UTC); other iMessage list endpoints (such as list connections and list contact rules) do not support them. All three are optional and fully backwards-compatible — omit them and the endpoint behaves exactly as before, with no filtering applied.

Parameter	Type	Default	Description
`start_datetime`	string	—	Inclusive lower bound. A bare date (`2026-07-01`) starts at 00:00 of that day; a datetime with a `Z` or offset is used as an exact instant
`end_datetime`	string	—	Upper bound, inclusive. A bare date (`2026-07-06`) covers the whole day; a datetime with a `Z` or offset is an exact instant, and records created at exactly that instant are included
`tz`	string	UTC	IANA time zone (e.g. `America/New_York`) used to interpret zone-less values. Defaults to UTC

A bare date in end_datetime is inclusive of the entire day — end_datetime=2026-07-06 returns records through the last moment of the 6th.
A datetime with an explicit Z or offset (2026-07-06T15:30:00Z, 2026-07-06T11:30:00-04:00) is an exact instant; tz is ignored for that value.
A naive datetime (2026-07-01T12:00:00) is interpreted in tz (UTC when tz is omitted).
Supply only one side for an open-ended range. Ordering, pagination, and all other filters are unchanged.
Invalid input returns 422: start_datetime after end_datetime, an unparseable date, or an unknown time zone.

A bare-date range (interpreted in UTC):

?start_datetime=2026-07-01&end_datetime=2026-07-06

Interpret those bare dates in a specific zone:

?start_datetime=2026-07-01&end_datetime=2026-07-06&tz=America/New_York

Filter from an exact instant (tz ignored):

?start_datetime=2026-07-06T15:30:00Z

​Quick start

Get API key

​Dedicated lines

​List dedicated lines

​Response (200)

​Claim a dedicated line

​Request body

​Response (201)

​Idempotency

​Error responses

​Router

Get router number

​Messaging capability

Check messaging capability

​Messages

Send message

Get message

Get a reply thread

List messages

Upload media

​Conversations

Connect a recipient

Disconnect a recipient

List conversations

Get conversation

Get conversation thread

List connections

Release connection

Mark conversation read

Send typing indicator

​Tapbacks

Send tapback

Remove tapback

​Contact rules

List contact rules

Create contact rule

Get contact rule

Update contact rule

Delete contact rule

List org iMessage contact rules

​Webhooks

​Filtering by date

​Additional resources

Quick start

Dedicated lines

List dedicated lines

Response (200)

Claim a dedicated line

Request body

Response (201)

Idempotency

Error responses

Router

Messaging capability

Messages

Conversations

Tapbacks

Contact rules

Webhooks

Filtering by date

Additional resources