Messages

Send and list 1:1 or group iMessages. iMessage requests are scoped to the agent identity and keyed by conversation_id; callers never choose a sending number in the message request. Shared lines remain hidden, while an attached dedicated line lets the identity start a conversation or group.

Send message

POST /messages

Send an outbound iMessage. Pass conversation_id to reply into an existing conversation, or to as either one E.164 phone number or a list of 1-8 E.164 phone numbers — exactly one of the two. Shared-service identities can reply only after the recipient has started a conversation. A dedicated line can start a new 1:1 conversation or a group chat; lists with 2-8 recipients select group behavior, while a scalar or one-item list keeps the 1:1 behavior. Reply into a conversation:

JSON

{
  "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
  "text": "On it — give me two minutes."
}

Or address the connected recipient directly:

JSON

{
  "to": "+15555550123",
  "text": "Done!",
  "send_style": "confetti"
}

Or start or select a group from a dedicated line:

JSON

{
  "to": ["+14155550100", "+14155550101"],
  "text": "Planning starts at 10.",
  "send_style": "confetti"
}

For groups, an unresolved local conversation with the same requested members is reused before a remote thread has been established. An established best-known match is reused only when its current membership can be verified and still matches the request. If no reusable match remains, a new group is created; multiple best-known matches return 409. A different to set never edits an existing group’s membership. Keep the returned conversation_id and use it to continue the exact same thread. See Group chats for membership and delivery semantics.

Query parameters

Parameter	Type	Description
`agent_identity_id`	UUID	The identity to send as. Required for admin API keys when sending by `to`; ignored for identity-scoped API keys, which always send as their own identity

Request body

Field	Type	Required	Description
`to`	string \| string[]	Conditional	One E.164 phone number, or 1-8 distinct E.164 phone numbers. A list with 2 or more recipients starts or selects a group. Mutually exclusive with `conversation_id`
`conversation_id`	UUID	Conditional	Existing conversation to reply into. Mutually exclusive with `to`
`text`	string \| null	No	Message body, up to 18,995 characters. Required unless `media_urls` has an item
`media_urls`	string[] \| null	No	Publicly fetchable media URL to attach — at most 1 entry. Use Upload media to turn raw bytes into a URL. Required unless `text` is present
`send_style`	string \| null	No	Expressive send style applied to a 1:1 or group message, including group creation and conversation replies. Can accompany text, media, or both

Preconditions

Identity opt-in. The sending identity must have imessage_enabled: true; otherwise sends return 400.
Line capability. Shared service requires recipient-first contact. A dedicated line can start 1:1 conversations and is required for groups.
Group participants. Group to lists contain 2-8 distinct remote E.164 phone numbers and cannot include the attached sending line. Every participant must pass opt-out and contact-rule checks before the message is queued.
Connection still active. If the recipient disconnected from the agent, sends into the old conversation return 409 until they reconnect through the router.
Contact rules. Sends to a recipient blocked by the identity’s contact rules return 403 before anything is sent.

Rate limits

Each agent identity can send up to 100 iMessages per rolling 24-hour window. When the cap is reached, 429 responses include:

Header	Description
`X-RateLimit-Limit`	Maximum sends allowed per identity per 24 hours
`X-RateLimit-Remaining`	Remaining 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

Dedicated lines carry additional guardrails on agent-initiated conversations. A dedicated line can start conversations with at most 10 new recipients per rolling 1-hour window and 40 new recipients per rolling 24-hour window, which keeps the line in good standing. Both limits apply only to recipients the line hasn’t reached before:

It does not apply to a recipient the agent has already connected with on that line.
It does not apply when the recipient messages the line first.

Repeat sends to an already-connected recipient never count against either limit. In a group chat, each previously unknown participant counts as one new recipient, and the whole request is rejected if the line lacks enough remaining slots in either window. At a cap, sends return 429 with error: "outbound_line_new_contact_rate_limited" and the same Retry-After and X-RateLimit-* headers. Those headers describe the limit that rejected the request, and Retry-After counts down until enough new-recipient slots in that window age out.

Response (201)

The queued message, wrapped in a message envelope. Delivery state updates asynchronously — re-read the message, or subscribe to the delivery-lifecycle webhooks (imessage.sent, imessage.delivered, imessage.delivery_failed) to track it without polling.

JSON

{
  "message": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
    "assignment_id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
    "direction": "outbound",
    "remote_number": "+15555550123",
    "sender_number": null,
    "participants": null,
    "is_group": false,
    "content": "On it — give me two minutes.",
    "message_type": "message",
    "service": "imessage",
    "send_style": null,
    "media": null,
    "was_downgraded": null,
    "status": "pending",
    "error_code": null,
    "error_message": null,
    "error_reason": null,
    "error_detail": null,
    "is_read": true,
    "is_blocked": false,
    "recipients": [
      {
        "remote_number": "+15555550123",
        "delivery_status": "pending",
        "service": "imessage",
        "error_code": null,
        "error_message": null,
        "error_reason": null,
        "error_detail": null,
        "sent_at": null,
        "delivered_at": null,
        "failed_at": null
      }
    ],
    "reactions": null,
    "created_at": "2026-06-09T14:30:00Z",
    "updated_at": "2026-06-09T14:30:00Z"
  }
}

Error responses

Status	Description
400	Sending identity is not enabled for iMessage, or `agent_identity_id` is missing on an admin send by `to`
402	The organization’s current billing-cycle iMessage capacity is exhausted
403	A recipient is blocked by a contact rule or has opted out
404	No connection exists for this recipient — the response tells you the connect command and router number to relay
404	`conversation_id` not found
409	The recipient hasn’t messaged this agent yet, has disconnected, a group send lacks a dedicated line, multiple groups match, current group membership is inconsistent or changes while resolving, or the line attachment changed
422	Invalid body: both/neither `to` and `conversation_id`, invalid or duplicate recipients, no text or media, more than one `media_urls` entry, or `text` over 18,995 characters
429	24-hour per-identity send limit or dedicated-line new-contact limit reached; respect the `Retry-After` header
503	`group_membership_unavailable` because current membership for an existing group could not be verified; retry with backoff

The 404 and 409 connection errors carry a structured detail — read detail.error to branch and detail.message for the sentence to relay:

`detail.error`	Meaning	Recovery
`imessage_no_assignment`	The recipient has never connected to this agent	Relay the connect command and router number named in `detail.message`, or the dedicated line to message first
`imessage_awaiting_inbound`	The recipient named in `detail.address` is connected, but has not sent the first message to the agent’s iMessage number	Ask them to text the agent’s number (not the router) first; only dedicated lines may initiate. `GET /identities/self/channel-status` lists these under `imessage.awaiting_inbound`
`imessage_assignment_inactive`	The recipient disconnected, so the old conversation is history	Have them reconnect, or start a new conversation on a dedicated line

Reactions, read receipts, and typing indicators return imessage_assignment_inactive the same way when the conversation’s assignment is no longer active. Delivery happens asynchronously after the 201, so delivery failures never surface as send-request errors. Re-read the message to observe every outcome; delivery-lifecycle transitions also emit webhooks. The first message in a new group also creates the group asynchronously. Check the conversation’s group_creation_status: "creating" while that attempt resolves, "ready" after success, or "not_created" after a definitive failure. During creating, the local conversation and pending messages exist before the remote thread does; another send to the same conversation waits behind the elected creation send. A failed first message remains in the same conversation’s history. Send another message using that conversation_id to retry group creation; a successful retry binds that same local conversation for later sends. Existing-group membership is rechecked before delivery, so a change after the 201 can instead move the queued message to status: "error". If you still intend to continue that native thread, a later conversation_id retry resolves its current membership again.

List messages

GET /messages

List iMessages visible to the caller, newest first, across all of the caller’s conversations or narrowed to one.

Query parameters

Parameter	Type	Default	Description
`agent_identity_id`	UUID	-	Narrow to one identity. Ignored for identity-scoped API keys, which always see their own identity
`conversation_id`	UUID	-	Narrow to one conversation
`include_groups`	boolean	false	Include group messages in list results. A known group `conversation_id` is read directly even when this remains false
`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` only non-blocked rows, and omitting it applies the caller’s default visibility
`start_datetime`	string	-	Only messages created on or after this date/time
`end_datetime`	string	-	Only messages 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 messages, regardless of is_blocked. Admin API keys and the Inkbox Console see blocked and non-blocked messages by default; use is_blocked=true for a blocked-only audit 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)

Returns a list[IMessage]. Live tapbacks ride along on each message — see the Message object.

JSON

[
  {
    "id": "1a90e8b0-0e1e-485f-b316-28f7dfa96afd",
    "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
    "assignment_id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
    "direction": "inbound",
    "remote_number": "+15555550123",
    "sender_number": null,
    "participants": null,
    "is_group": false,
    "content": "Can you move my 3pm?",
    "message_type": "message",
    "service": "imessage",
    "send_style": null,
    "media": null,
    "was_downgraded": null,
    "status": "received",
    "error_code": null,
    "error_message": null,
    "error_reason": null,
    "error_detail": null,
    "is_read": false,
    "is_blocked": false,
    "recipients": null,
    "reactions": [
      {
        "id": "0f6b8a5e-1ca0-4a4f-8e94-44b3e4374f9a",
        "direction": "outbound",
        "reaction": "like",
        "custom_emoji": null,
        "remote_number": "+15555550123",
        "part_index": 0,
        "created_at": "2026-06-09T14:31:00Z"
      }
    ],
    "created_at": "2026-06-09T14:30:00Z",
    "updated_at": "2026-06-09T14:31:00Z"
  }
]

Error responses

Status	Description
400	`agent_identity_id` names an identity that is not enabled for iMessage
403	Identity-scoped key passed an `agent_identity_id` other than its own
404	`agent_identity_id` or `conversation_id` not found, or not visible to the caller

Upload media

POST /media

Upload a file and get back a URL you can pass in media_urls on a send. The request is multipart/form-data with a single file field.

Request

Field	Type	Required	Description
`file`	file	Yes	The file to upload, up to 10 MiB. The part’s content type and filename are preserved

Response (201)

JSON

{
  "media_url": "https://media.example.com/abc123_chart.png",
  "content_type": "image/png",
  "size": 48211
}

Error responses

Status	Description
400	Caller’s identity is not enabled for iMessage
413	File exceeds 10 MiB
502	Upstream upload failure — safe to retry

Send styles

Pass send_style on a 1:1 or group send to apply one of Apple’s expressive effects. Dedicated-line groups support styles on both creation and conversation_id replies, including messages that also carry the single allowed media item:

Bubble effects	Full-screen effects
`slam`	`celebration`
`loud`	`shooting_star`
`gentle`	`fireworks`
`invisible` (invisible ink)	`lasers`
	`love`
	`confetti`
	`balloons`
	`spotlight`
	`echo`

Send styles render on the recipient’s device when the message is delivered over iMessage; they do not apply to SMS fallback.

Message object

Field	Type	Description
`id`	string (UUID)	Message ID
`conversation_id`	string (UUID)	The conversation this message belongs to
`assignment_id`	string (UUID) \| null	The 1:1 connection carrying the conversation; null for group messages
`direction`	string	`"inbound"` or `"outbound"`
`remote_number`	string \| null	The human’s E.164 phone number for 1:1 messages. On inbound group messages it mirrors `sender_number`; null on outbound group messages
`sender_number`	string \| null	Sender’s E.164 phone number on an inbound group message; null for 1:1 and outbound group messages
`participants`	string[] \| null	Best-known E.164 participant snapshot for a group message; null for 1:1 messages
`is_group`	boolean	Whether the message belongs to an iMessage group chat
`content`	string \| null	Message body. Null for media-only messages
`message_type`	string	`"message"`, or `"carousel"` for rich multi-part messages
`service`	string	Transport actually used: `"imessage"`, `"sms"`, or `"rcs"`
`send_style`	string \| null	Send style applied to the message, if any
`media`	array \| null	Media attachments. Each item has `url`, `content_type`, and `size`. URLs for stored inbound media are presigned and expire after 1 hour
`was_downgraded`	boolean \| null	Whether delivery fell back from iMessage to SMS
`status`	string \| null	Delivery lifecycle: `"registered"`, `"pending"`, `"queued"`, `"accepted"`, `"sent"`, `"delivered"`, `"declined"`, `"error"`, or `"received"` for inbound
`error_code`	string \| null	Delivery error code, when delivery failed
`error_message`	string \| null	Short delivery error description
`error_reason`	string \| null	Delivery error reason, when reported
`error_detail`	string \| null	Human-readable detail accompanying the error
`is_read`	boolean	Read state. For inbound messages, set by mark-read
`is_blocked`	boolean	Whether the message was blocked by a contact rule or by default-block in whitelist mode. Identity-scoped API keys never receive rows where this is `true`
`recipients`	array \| null	Per-recipient delivery state for outbound messages, including one entry per group participant; null for inbound. Each entry has `remote_number`, `delivery_status`, `service`, error fields, and `sent_at` / `delivered_at` / `failed_at` timestamps
`reactions`	array \| null	Live tapbacks targeting this message, oldest first. Each entry has `id`, `direction`, `reaction`, `custom_emoji`, `remote_number`, `part_index`, and `created_at`
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Send message

Query parameters

Request body

Preconditions

Rate limits

Response (201)

Error responses

List messages

Query parameters

Response (200)

Error responses

Upload media

Request

Response (201)

Error responses

Send styles

Message object

​Send message

​Query parameters

​Request body

​Preconditions

​Rate limits

​Response (201)

​Error responses

​List messages

​Query parameters

​Response (200)

​Error responses

​Upload media

​Request

​Response (201)

​Error responses

​Send styles

​Message object

Send message

Query parameters

Request body

Preconditions

Rate limits

Response (201)

Error responses

List messages

Query parameters

Response (200)

Error responses

Upload media

Request

Response (201)

Error responses

Send styles

Message object