> ## 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.

# Introduction

> The iMessage API for agents

Messages.dev is the iMessage API for agents. Send and receive messages,
attachments, audio messages, reactions, typing indicators, and read receipts
over a simple REST API or [TypeScript SDK](/sdk).

<CardGroup cols={2}>
  <Card title="Send messages" icon="paper-plane" href="/guides/send-message">
    Text, attachments, and threaded replies. Group chats supported.
  </Card>

  <Card title="Receive messages" icon="inbox" href="/guides/receive-messages">
    Get notified instantly via signed webhooks when messages arrive.
  </Card>

  <Card title="Audio messages" icon="microphone" href="/guides/audio-messages">
    Native iMessage waveform balloons, with on-device transcription on inbound voice memos.
  </Card>

  <Card title="Contact cards" icon="address-card" href="/guides/contact-cards">
    Send rich vCards the recipient can save with one tap.
  </Card>

  <Card title="Reactions" icon="heart" href="/guides/reactions">
    Send and receive iMessage reactions (love, like, laugh, emphasize, etc.).
  </Card>

  <Card title="Typing & read receipts" icon="eye" href="/guides/typing-indicators">
    Send typing indicators and mark conversations as read.
  </Card>
</CardGroup>

## What you can do

| Capability                                    | How                                              | Reference                                                                   |
| --------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- |
| Send text                                     | `POST /v1/messages`                              | [Send a message](/guides/send-message)                                      |
| Send attachments (images, video, docs)        | `POST /v1/files` then `POST /v1/messages`        | [Attachments](/guides/attachments)                                          |
| Send native audio messages                    | `POST /v1/files` then `POST /v1/audio-messages`  | [Audio messages](/guides/audio-messages)                                    |
| Send vCard contact cards                      | `client.sendContactCard(...)`                    | [Contact cards](/guides/contact-cards)                                      |
| Reply to a specific message                   | `reply_to` field on `POST /v1/messages`          | [Send a message](/guides/send-message#reply-to-a-specific-message)          |
| Send into group chats                         | Pass a `cht_...` chat ID as `to`                 | [Group chats](/guides/group-chats)                                          |
| Send reactions                                | `POST /v1/reactions`                             | [Reactions](/guides/reactions)                                              |
| Send typing indicators                        | `POST /v1/typing`                                | [Typing indicators](/guides/typing-indicators)                              |
| Mark a chat as read                           | `POST /v1/receipts`                              | [Read receipts](/guides/read-receipts)                                      |
| Receive messages, reactions, typing, receipts | Webhooks (HMAC-signed)                           | [Webhooks](/concepts/webhooks)                                              |
| Receive voice memos with transcription        | `message.received` with `is_audio_message: true` | [Audio messages › Receive](/guides/audio-messages#receive-an-audio-message) |
| Track delivery                                | `GET /v1/outbox` or `message.sent` webhook       | [Send a message › Track delivery](/guides/send-message#track-delivery)      |

<Note>
  **Contact-first.** Outside the sandbox, the recipient must message your line
  before you can send to them. See [Send a message › Contact-first
  restriction](/guides/send-message#contact-first-restriction).
</Note>

## How it works

1. **Sign up** at [app.messages.dev](https://app.messages.dev) and create an API key
2. **Activate your sandbox**: text an activation code to the sandbox number to pair your phone
3. **Send** messages, reactions, and typing indicators via the [TypeScript SDK](/sdk) (recommended) or the REST API directly
4. **Receive** incoming messages and events in real time via webhooks

The TypeScript SDK is the recommended way to integrate. It wraps every
endpoint with a typed client, handles cursor pagination, throws typed errors,
and verifies webhook signatures correctly out of the box.

For local development and one-off scripting, the
[`messages-dev` CLI](/cli) is the fastest path.
[`listen --forward-to <url>`](/cli#forward-live-events-to-a-local-webhook-handler)
streams live events into a local handler with the same HMAC headers
production webhooks use, so you can build and test webhook handlers without
ngrok or a registered webhook.

<CodeGroup>
  ```typescript TypeScript (recommended) theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  import { createClient } from "@messages-dev/sdk";

  const client = createClient(); // reads MESSAGES_API_KEY

  await client.sendMessage({
    from: "+15551234567",
    to: "+15559876543",
    text: "Hello from Messages.dev!",
  });
  ```

  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  curl -X POST "https://api.messages.dev/v1/messages" \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{"from": "+15551234567", "to": "+15559876543", "text": "Hello from Messages.dev!"}'
  ```
</CodeGroup>

Not on TypeScript? Every example in these docs ships a `curl` tab too — the
SDK is a convenience layer, not a requirement.

```json theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
{
  "event": "message.received",
  "data": {
    "id": "msg_abc123",
    "sender": "+15559876543",
    "text": "Hey, got your message!",
    "sent_at": 1710000005000
  }
}
```

## Key concepts

| Concept      | Description                                                                                                                                                       |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Lines**    | Your iMessage phone numbers or Apple IDs. Each line is a separate iMessage account. [Scale across multiple lines](/scaling/multiple-lines) once one isn't enough. |
| **Chats**    | Conversations on a line, identified by the recipient's phone number or Apple ID.                                                                                  |
| **Webhooks** | HTTPS callbacks that notify your server when events happen (new message, delivery confirmation, etc.).                                                            |
| **API keys** | Bearer tokens you create in the [dashboard](https://app.messages.dev). Keys have configurable scopes and optional line restrictions.                              |

## Get started

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Send your first message in 5 minutes
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdk">
    Recommended for TypeScript / Node.js
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    `messages-dev` — send from your terminal and stream live events into a
    local handler. Best path for local dev.
  </Card>

  <Card title="REST API Reference" icon="code" href="/api-reference/overview">
    Use the API directly from any language
  </Card>
</CardGroup>

## Going to production

<CardGroup cols={2}>
  <Card title="Limits" icon="gauge" href="/scaling/limits">
    Per-line throughput and daily volume guidance.
  </Card>

  <Card title="Multiple lines" icon="network-wired" href="/scaling/multiple-lines">
    Scale by spreading users across more lines.
  </Card>
</CardGroup>