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:
https://inkbox.ai/api/v1/imessageQuick start
Create an account and get your API key from the Inkbox console:
Get API keyAll API requests require authentication using a API key:
X-API-Key: YOUR_API_KEYTwo things to know before your first call:
- iMessage is opt-in per identity. Set
imessage_enabled: truewhen creating or updating an identity. - The human texts first. Recipients connect by texting
connect @your-handleto the router number; agents reply after that. There is no cold outreach over iMessage.
Router
Messages
Send message
POSTReply to a connected recipient by conversation or by number
/api/v1/imessage/messagesList messages
GETList iMessages visible to the caller, newest first
/api/v1/imessage/messagesUpload media
POSTUpload a file and get a URL usable in media_urls
/api/v1/imessage/mediaConversations
List conversations
GETList conversation summaries with latest-message previews and unread counts
/api/v1/imessage/conversationsGet conversation
GETGet a single conversation by ID
/api/v1/imessage/conversations/{conversation_id}List connections
GETList recipients currently connected to an agent identity
/api/v1/imessage/assignmentsMark conversation read
POSTSend a read receipt and mark inbound messages read
/api/v1/imessage/mark-readSend typing indicator
POSTShow the typing bubble to the conversation's recipient
/api/v1/imessage/typingTapbacks
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 and the iMessage guide for semantics.
List contact rules
GETList allow/block rules for an agent identity
/api/v1/imessage/identities/{agent_handle}/contact-rulesCreate contact rule
POSTAdd an allow or block rule (E.164 exact match)
/api/v1/imessage/identities/{agent_handle}/contact-rulesGet contact rule
GETFetch a single rule by ID
/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}Update contact rule
PATCHChange action or status (admin-only)
/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}Delete contact rule
DELETEDelete a rule (admin-only)
/api/v1/imessage/identities/{agent_handle}/contact-rules/{rule_id}List org iMessage contact rules
GETOrg-wide aggregate list across every identity (admin-only)
/api/v1/imessage/contact-rulesWebhooks
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.
