# Message.com iMessage integration

Canonical guide: https://www.message.com/developers/rest-api/imessage
OpenAPI: https://www.message.com/developers/imessage-openapi.json

Create a key at Settings > iMessage > API & integrations. Permissions: mcp:imessage:read, mcp:imessage:send. The key also has mcp:connect for shared authorization. Send Authorization: Bearer KEY from your backend only. Never expose keys in browser code or prompts.

Base URL: https://app.message.com/api/v1/integrations/imessage
GET /lines -> {lines:[{id,lineNumber,kind,status,requestedAreaCode}]}
GET /usage -> current line usage and limits.
GET /messages?lineId=UUID&limit=50&after=ISO_TIMESTAMP&afterId=UUID -> {messages,hasMore,cursor:{after,afterId}}. Both cursor fields required together. Poll every 5-10 seconds, deduplicate by message ID. Re-read the original time range to refresh delivery status (the cursor follows creation time, not status updates).
POST /send JSON: {requestId:UUID,lineId:UUID,to:E164,body:TEXT}. Save requestId with your job. Retries must use identical requestId and payload. Response gives conversationId/messageId, not proof of delivery.

STOP, reply-only package rules, warmup and usage limits apply to API and MCP. Pending/paused/banned lines cannot send. There is no SMS fallback. Customer webhooks are not available; use polling. 400 invalid input; 401/403 authorization/policy; 402 payment access; 404 unavailable line; 409 request_id_conflict or action_in_progress_or_uncertain; 429 limit; 503 uncertain/unavailable. Never retry an uncertain send with a new request ID. Check Inbox first.

MCP endpoint: https://app.message.com/api/v1/mcp
Tools: list_imessage_lines, list_imessage_messages, imessage_usage, send_imessage.