Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# iMessage API
description: API-first iMessage for AI agents — connect humans through the Inkbox iMessage router, read and reply in conversations, send tapbacks, attach media, and subscribe to events via webhooks

---


# iMessage API

API-first iMessage for AI agents. Humans connect to an agent through the shared Inkbox iMessage router; from there your agent reads and replies in conversations, sends tapbacks, read receipts, typing indicators, and media, and subscribes to inbound events via webhooks.

API base URL:


## Quick start

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

[Get API key](https://inkbox.ai/console/api-keys)

All API requests require authentication using a API key:


Two things to know before your first call:

- **iMessage is opt-in per identity.** Set `imessage_enabled: true` when [creating or updating an identity](/docs/api/identities/manage).
- **The human texts first.** Recipients connect by texting `connect @your-handle` to the [router number](/docs/api/imessage/router); agents reply after that. There is no cold outreach over iMessage.

## Router


  **[Get router number](/docs/api/imessage/router)** `GET` `/api/v1/imessage/triage-number` — The active router number and the command humans text to connect


## Messages


  **[Send message](/docs/api/imessage/messages)** `POST` `/api/v1/imessage/messages` — Reply to a connected recipient by conversation or by number

  **[List messages](/docs/api/imessage/messages)** `GET` `/api/v1/imessage/messages` — List iMessages visible to the caller, newest first

  **[Upload media](/docs/api/imessage/messages)** `POST` `/api/v1/imessage/media` — Upload a file and get a URL usable in media_urls


## Conversations


  **[List conversations](/docs/api/imessage/conversations)** `GET` `/api/v1/imessage/conversations` — List conversation summaries with latest-message previews and unread counts

  **[Get conversation](/docs/api/imessage/conversations)** `GET` `/api/v1/imessage/conversations/{conversation_id}` — Get a single conversation by ID

  **[List connections](/docs/api/imessage/conversations#list-connections)** `GET` `/api/v1/imessage/assignments` — List recipients currently connected to an agent identity

  **[Mark conversation read](/docs/api/imessage/conversations)** `POST` `/api/v1/imessage/mark-read` — Send a read receipt and mark inbound messages read

  **[Send typing indicator](/docs/api/imessage/conversations)** `POST` `/api/v1/imessage/typing` — Show the typing bubble to the conversation's recipient


## Tapbacks


  **[Send tapback](/docs/api/imessage/reactions)** `POST` `/api/v1/imessage/reactions` — React to a message; a new tapback replaces your previous one


## Contact rules

Per-identity allow and block rules interpreted against the identity's iMessage `filter_mode` (`blacklist` by default, `whitelist` on demand). Rules are scoped to the agent identity because there is no per-identity iMessage number. See the [Contact rules reference](/docs/api/imessage/contact-rules) and the [iMessage guide](/docs/capabilities/imessage#filtering-who-can-reach-your-agent) for semantics.


  **[List contact rules](/docs/api/imessage/contact-rules)** `GET` `/api/v1/imessage/identities/{agent_handle}/contact-rules` — List allow/block rules for an agent identity

  **[Create contact rule](/docs/api/imessage/contact-rules)** `POST` `/api/v1/imessage/identities/{agent_handle}/contact-rules` — Add an allow or block rule (E.164 exact match)

  **[Get contact rule](/docs/api/imessage/contact-rules)** `GET` `/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}` — Fetch a single rule by ID

  **[Update contact rule](/docs/api/imessage/contact-rules)** `PATCH` `/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}` — Change action or status (admin-only)

  **[Delete contact rule](/docs/api/imessage/contact-rules)** `DELETE` `/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}` — Delete a rule (admin-only)

  **[List org iMessage contact rules](/docs/api/imessage/contact-rules#list-org-imessage-contact-rules)** `GET` `/api/v1/imessage/contact-rules` — Org-wide aggregate list across every identity (admin-only)


## 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](/docs/api/webhooks/subscriptions) — attach a subscription to the **agent identity** with the subset you want. See the [iMessage webhooks reference](/docs/api/imessage/webhooks) for event types, payload format, and signature verification.

## Additional resources

- [iMessage guide](/docs/capabilities/imessage)
- [Agent Identity API](/docs/api/identities)
- [Webhook Subscriptions API](/docs/api/webhooks/subscriptions)
- [Phone API](/docs/api/phone)