Skip to main content
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

CapabilityHowReference
Send textPOST /v1/messagesSend a message
Send attachments (images, video, docs)POST /v1/files then POST /v1/messagesAttachments
Send native audio messagesPOST /v1/files then POST /v1/audio-messagesAudio messages
Send vCard contact cardsclient.sendContactCard(...)Contact cards
Reply to a specific messagereply_to field on POST /v1/messagesSend a message
Send into group chatsPass a cht_... chat ID as toGroup chats
Send reactionsPOST /v1/reactionsReactions
Send typing indicatorsPOST /v1/typingTyping indicators
Mark a chat as readPOST /v1/receiptsRead receipts
Receive messages, reactions, typing, receiptsWebhooks (HMAC-signed)Webhooks
Receive voice memos with transcriptionmessage.received with is_audio_message: trueAudio messages › Receive
Track deliveryGET /v1/outbox or message.sent webhookSend 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. 
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!",
});
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

ConceptDescription
LinesYour iMessage phone numbers or Apple IDs. Each line is a separate iMessage account. Scale across multiple lines once one isn’t enough.
ChatsConversations on a line, identified by the recipient’s phone number or Apple ID.
WebhooksHTTPS callbacks that notify your server when events happen (new message, delivery confirmation, etc.).
API keysBearer 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.