iMessage API

API-first iMessage for AI agents. Use the shared Inkbox iMessage router or attach a dedicated number, 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

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

All API requests require authentication using an API key:

X-API-Key: YOUR_API_KEY

Three things to know before your first call:

• iMessage is opt-in per identity. Set imessage_enabled: true when creating or updating an identity.
• The number type defines what the identity can do. An outbound number can start new conversations. An inbound number can reply in existing conversations. The shared service dynamically assigns a number when someone connects to your agent.
• Shared and inbound conversations start with the human. Recipients connect to a shared identity by texting connect @your-handle to the router number. A dedicated outbound number can start a new conversation.
• Group chats require a dedicated outbound number. Use the existing send endpoint with 2-8 E.164 recipients, then keep the returned conversation_id as the canonical group key. 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 numbers belong to your organization and can be attached to an iMessage-enabled identity. The type field is the capability source:

List dedicated numbers GET

GET /numbers

Returns every dedicated iMessage number owned by the caller's organization, including numbers that are not attached to an identity.

Response (200)

JSON

bash

Claim a dedicated number POST

POST /numbers

Claims one unattached dedicated number for the organization. Use an admin API key, or manage dedicated numbers from the Inkbox Console.

The request requires a stable key in the Idempotency-Key header:

Idempotency-Key: <unique stable key>

Request body

JSON

type may be dedicated_inbound or dedicated_outbound.

Response (201)

Returns one unattached dedicated-number object with the same schema as the list endpoint:

JSON

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

Error responses

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

/api/v1/imessage/triage-number

/api/v1/imessage/check-messaging-capability

/api/v1/imessage/messages

/api/v1/imessage/messages

/api/v1/imessage/media

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

/api/v1/imessage/conversations

/api/v1/imessage/conversations/{conversation_id}

/api/v1/imessage/assignments

/api/v1/imessage/mark-read

/api/v1/imessage/typing

/api/v1/imessage/reactions

Per-identity allow and block rules interpreted against the identity's iMessage filter_mode (blacklist by default, whitelist on demand). Rules stay scoped to the agent identity whether it uses the shared service or a dedicated number. See the Contact rules reference and the iMessage guide for semantics.

/api/v1/imessage/identities/{agent_handle}/contact-rules

/api/v1/imessage/identities/{agent_handle}/contact-rules

/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}

/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}

/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}

/api/v1/imessage/contact-rules

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.

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.

• 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

• iMessage guide
• Agent Identity API
• Webhook Subscriptions API
• Phone API