Introduction

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.

Send messages

Text, attachments, and threaded replies. Group chats supported.

Receive messages

Get notified instantly via signed webhooks when messages arrive.

Audio messages

Native iMessage waveform balloons, with on-device transcription on inbound voice memos.

Contact cards

Send rich vCards the recipient can save with one tap.

Reactions

Send and receive iMessage reactions (love, like, laugh, emphasize, etc.).

Typing & read receipts

Send typing indicators and mark conversations as read.

What you can do

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

Contact-first. Outside the sandbox, the recipient must message your line before you can send to them. See Send a message › Contact-first restriction.

How it works

Sign up at app.messages.dev and create an API key
Activate your sandbox: text an activation code to the sandbox number to pair your phone
Send messages, reactions, and typing indicators via the TypeScript SDK (recommended) or the REST API directly
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 is the fastest path. listen --forward-to <url> 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.

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!",
});

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!"}'

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

{
  "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 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. Keys have configurable scopes and optional line restrictions.

Get started

Quickstart

Send your first message in 5 minutes

TypeScript SDK

Recommended for TypeScript / Node.js

CLI

messages-dev — send from your terminal and stream live events into a local handler. Best path for local dev.

REST API Reference

Use the API directly from any language

Going to production

Limits

Per-line throughput and daily volume guidance.

Multiple lines

Scale by spreading users across more lines.

Getting Started

Guides

Concepts

Scaling

Send messages

Receive messages

Audio messages

Contact cards

Reactions

Typing & read receipts

What you can do

How it works

Key concepts

Get started

Quickstart

TypeScript SDK

CLI

REST API Reference

Going to production

Limits

Multiple lines

Send messages

Receive messages

Audio messages

Contact cards

Reactions

Typing & read receipts

​What you can do

​How it works

​Key concepts

​Get started

Quickstart

TypeScript SDK

CLI

REST API Reference

​Going to production

Limits

Multiple lines

What you can do

How it works

Key concepts

Get started

Going to production