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

POST /v1/messages

Send a message

cURL

curl --request POST \
  --url https://api.messages.dev/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "[phone]",
  "to": "[phone]",
  "text": "Hello from Messages.dev!",
  "attachments": [
    "file_abc123"
  ],
  "reply_to": "msg_abc123"
}
'

201

{
  "id": "<string>",
  "status": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization · string · header · required

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.

Body

application/json

from · string · required

Sender line handle (phone number or Apple ID)

Example:

"[phone]"

to · string · required

Recipient phone number, Apple ID, or chat ID (cht_... for group chats)

Example:

"[phone]"

text · string

Message text (at least one of text or attachments required)

Example:

"Hello from Messages.dev!"

attachments · string[]

Array of file IDs (max 1). Upload files via POST /v1/files first.

Maximum array length: 1

Example:

["file_abc123"]

reply_to · string

Message ID (msg_...) or iMessage GUID to reply to

Example:

"msg_abc123"

Response

201

application/json

Outbox item created

id · string

Delivery ID (e.g. obx_abc123)

status · string

Allowed value: "pending"

request_id · string