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:

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

All API requests require authentication using an 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.
• Shared-service conversations start with the human. Recipients connect to a shared identity by texting connect @your-handle to the router number.
• 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 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.

List dedicated lines GET

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

Response (200)

Claim a dedicated line POST

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:

Request body

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.

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.

Error responses

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.

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

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 shared service or a dedicated line. See the Contact rules reference and the iMessage guide for semantics.

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):

Interpret those bare dates in a specific zone:

Filter from an exact instant (tz ignored):

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