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.

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

1. Sign up at 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 (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 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.

TypeScript (recommended)

import { createClient } from "@messages-dev/sdk";

const client = createClient(); // reads MESSAGES_API_KEY

await client.sendMessage({
  from: "[phone]",
  to: "[phone]",
  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": "[phone]",
    "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.