> ## Documentation Index > Fetch the complete documentation index at: https://messages.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Send a message > Sends an iMessage or SMS. Returns a delivery ID with `status: "pending"`. Use `GET /outbox` or webhooks to track delivery. **Contact-first restriction**: outside the sandbox, the recipient must have messaged your line first. If they haven't, the request returns `403 contact_has_not_messaged`. **Group chats**: pass a chat ID (`cht_...`) returned from `GET /v1/chats` as `to`. Group chats also follow the contact-first rule: at least one inbound message must have been received in the chat. **Replies**: pass `reply_to` (a `msg_...` ID or raw iMessage GUID) to thread a reply to a specific message. **Attachments**: upload a file via `POST /v1/files` and pass its `file_...` ID in the `attachments` array. At least one of `text` or `attachments` is required. To send an audio message that renders as a native voice-memo balloon, use `POST /v1/audio-messages` instead. To send a vCard contact card, upload the `.vcf` file and pass its file ID in `attachments` (no `text` needed). ## OpenAPI ````yaml POST /v1/messages openapi: 3.1.0 info: title: Messages.dev API version: '1.0' description: > The Messages.dev API lets you send and receive iMessages programmatically. ## Recommended: use the TypeScript SDK `@messages-dev/sdk` (`npm install @messages-dev/sdk`) is the recommended integration for TypeScript and Node.js. It wraps every endpoint below with a typed client, handles cursor pagination, throws typed errors, and ships `verifyWebhook()` which gets the HMAC scheme right (`HMAC(${timestamp}.${body})` with replay protection). See the [SDK reference](/sdk). The REST API documented here is the underlying transport — use it directly from any language without TypeScript. ## Conventions All endpoints are prefixed with `/v1` and return JSON. Request and response fields use `snake_case`. All IDs include a type prefix (e.g. `msg_`, `cht_`). Write operations (POST /messages, /audio-messages, /reactions, /typing, /receipts) are **asynchronous**. They return a delivery ID with `status: "pending"`. Use `GET /outbox` or webhooks to track delivery. ## Capabilities - Send and receive text messages, with optional file attachments and reply-to threading. - Send native iMessage **audio messages** (waveform balloon) via `POST /v1/audio-messages`. Inbound voice memos arrive on `message.received` with `is_audio_message: true` and include Apple's on-device `transcription`. - Send **iMessage reactions** (`love`, `like`, `dislike`, `laugh`, `emphasize`, `question`) via `POST /v1/reactions`. Receive inbound reactions via the `reaction.added` / `reaction.removed` webhooks. - Send **typing indicators** and **read receipts**. - Upload files and send them as attachments (or as **vCard contact cards** — see Recipes). - **Group chats**: send to a `cht_...` chat ID returned by `GET /v1/chats`. - **Webhooks** for `message.received`, `message.sent`, `reaction.added`, `reaction.removed`. Signed with HMAC-SHA256 over `${timestamp}.${body}`. ## Contact-first restriction To protect lines from being flagged as spammers, you can only send to a contact after they have messaged your line first. Attempting to send to a contact that has not messaged in returns `403 contact_has_not_messaged`. The sandbox line is pre-paired with your phone number once you activate it. ## Recipes A few capabilities are compositions of existing endpoints rather than a dedicated route. The SDK wraps each as a single call. | Capability | Mechanism | SDK helper | |---|---|---| | Send a contact card | `POST /v1/files` (`Content-Type: text/vcard`) → `POST /v1/messages` with the returned file ID in `attachments` | `client.sendContactCard()` | | Send a native audio message | `POST /v1/files` (audio mime) → `POST /v1/audio-messages` with the file ID as `audio_message` | `client.sendAudioMessage()` | | Reply to a specific message | `POST /v1/messages` with `reply_to: "msg_..."` (or a raw iMessage GUID) | `replyTo` parameter on every send method | | Send into a group chat | `POST /v1/messages` with a `cht_...` chat ID as `to`. Discover chats via `GET /v1/chats`. | Same `to` parameter | | Test webhooks locally | Build a real signed delivery yourself, then POST it to your handler — `verifyWebhook()` accepts it without a test-mode flag. | `signWebhook` / `buildWebhookDelivery` | servers: - url: https://api.messages.dev description: Messages.dev API security: - BearerAuth: [] tags: - name: Lines description: Your iMessage phone numbers and Apple IDs - name: Chats description: Conversations on a line - name: Messages description: Send and retrieve messages - name: Reactions description: iMessage reactions (love, like, etc.) on messages - name: Typing description: Typing indicators - name: Read Receipts description: Read receipt tracking - name: Delivery description: Track delivery status of write operations - name: Files description: Upload and retrieve file attachments - name: Webhooks description: Real-time event notifications paths: /v1/messages: post: tags: - Messages summary: Send a message description: > Sends an iMessage or SMS. Returns a delivery ID with `status: "pending"`. Use `GET /outbox` or webhooks to track delivery. **Contact-first restriction**: outside the sandbox, the recipient must have messaged your line first. If they haven't, the request returns `403 contact_has_not_messaged`. **Group chats**: pass a chat ID (`cht_...`) returned from `GET /v1/chats` as `to`. Group chats also follow the contact-first rule: at least one inbound message must have been received in the chat. **Replies**: pass `reply_to` (a `msg_...` ID or raw iMessage GUID) to thread a reply to a specific message. **Attachments**: upload a file via `POST /v1/files` and pass its `file_...` ID in the `attachments` array. At least one of `text` or `attachments` is required. To send an audio message that renders as a native voice-memo balloon, use `POST /v1/audio-messages` instead. To send a vCard contact card, upload the `.vcf` file and pass its file ID in `attachments` (no `text` needed). operationId: send-message requestBody: required: true content: application/json: schema: type: object required: - from - to properties: from: type: string description: Sender line handle (phone number or Apple ID) example: '+15551234567' to: type: string description: >- Recipient phone number, Apple ID, or chat ID (`cht_...` for group chats) example: '+15559876543' text: type: string description: >- Message text (at least one of `text` or `attachments` required) example: Hello from Messages.dev! attachments: type: array description: >- Array of file IDs (max 1). Upload files via `POST /v1/files` first. items: type: string maxItems: 1 example: - file_abc123 reply_to: type: string description: Message ID (`msg_...`) or iMessage GUID to reply to example: msg_abc123 responses: '201': description: Outbox item created content: application/json: schema: $ref: '#/components/schemas/OutboxItemCreated' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ContactHasNotMessaged' '404': $ref: '#/components/responses/NotFound' components: schemas: OutboxItemCreated: type: object properties: id: type: string description: Delivery ID (e.g. `obx_abc123`) status: type: string const: pending request_id: type: string Error: type: object properties: error: type: object properties: type: type: string description: Error category enum: - authentication_error - authorization_error - invalid_request_error - not_found_error - rate_limit_error code: type: string description: Machine-readable error code message: type: string description: Human-readable error description param: type: string description: The parameter that caused the error, if applicable request_id: type: string description: Unique request identifier for debugging responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: missing_required_parameter message: The 'from' query parameter is required. param: from request_id: req_abc123 Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: authentication_error code: missing_api_key message: >- Missing Authorization header. Use 'Authorization: Bearer sk_live_...' request_id: req_abc123 ContactHasNotMessaged: description: | The recipient must message your line first. Returned when sending to a contact (or group chat) that has no inbound history. Sandbox lines bypass this rule once activated. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: contact_has_not_messaged message: Cannot send to a contact who has not messaged this line first. param: to request_id: req_abc123 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: not_found_error code: line_not_found message: Line not found. param: from request_id: req_abc123 securitySchemes: BearerAuth: type: http scheme: bearer description: | Use an API key as a bearer token: `Authorization: Bearer sk_live_...` Each key has a set of scopes that gate which endpoints it can call: `messages:read`, `messages:write`, `chats:read`, `lines:read`, `reactions:read`, `reactions:write`, `typing:read`, `typing:write`, `receipts:read`, `receipts:write`, `webhooks:read`, `webhooks:write`, `outbox:read`, `files:read`, `files:write`. Keys can also be restricted to a subset of lines. ````