API Reference

Messages

Send + receive iMessages. Send to one recipient or many. Edit, unsend, react. Schedule for later. Send attachments. Add iMessage effects. Reply with threading.

Send a message

POST/v1/messages

Send a single iMessage. Returns immediately; the message state is pushed via webhook as it transitions through sent → delivered → read.

curl -X POST 'https://api.bluereplies.com/v1/messages' \
  -H "x-api-key: $BLUEREPLIES_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+15551234567",
    "body": "Your appointment is tomorrow at 2pm.",
    "effect": "gentle"
  }'

Body parameters

Field	Type	Description
`to`required	string	Recipient phone in E.164 format. International is fine. e.g. `+15551234567`
`body`required	string	Message text. Up to 16,000 chars, but keep it under ~600 for best deliverability. e.g. `Hello!`
`from`	string	Pin to a specific line. Either the phone number (+1XXX) or the line ID (lin_…). If omitted, the router auto-picks based on area code, load, and warmup. e.g. `+12138765278`
`effect`	string	iMessage effect. One of `slam`, `loud`, `gentle`, `invisible`, `balloons`, `confetti`, `fireworks`, `celebration`, `lasers`, `love`, `echo`, `spotlight`.
`subject`	string	Subject line (bold preface above the body, like iOS Mail).
`mediaUrls`	string[]	URLs of attachments to send. Images, videos, audio (m4a/caf), files. Max 10 per message.
`isVoiceNote`	booleandefault `false`	When true with one audio mediaUrl, deliver as a native iMessage voice memo (afconvert → Opus/CAF on our side).
`replyTo`	string	BlueReplies message ID being replied to. Renders as a quoted-reply thread in the recipient's Messages app. e.g. `msg_abc123`
`scheduledAt`	string (ISO 8601)	Schedule the send for the future. Up to 30 days out. e.g. `2026-06-01T17:00:00Z`
`webhookUrl`	string	Per-message webhook URL. Fires sent/delivered/read updates ONLY for this message, in addition to your account-level webhooks.
`allowSmsFallback`	booleandefault `true`	If the recipient is not iMessage-capable, attempt SMS via Telnyx. Requires SMS fallback enabled on your account.
`idempotencyKey`	string	Dedupe key. If you POST twice with the same key within 24h, the second request returns the original message id. See Idempotency.
`maxRetries`	integerdefault `3`	How many times to retry on transient delivery failure. 1-10.

Response

{
  "id": "msg_pq3z9Vc7BmHkLxQ1aWoZP",
  "status": "queued",
  "from": "+12138765278",
  "to": "+15551234567",
  "body": "Your appointment is tomorrow at 2pm.",
  "effect": "gentle",
  "lineId": "lin_a802426485c04055f82cafd3",
  "createdAt": "2026-05-25T17:23:14.221Z"
}

Status callbacks

Subscribe to message.delivered + message.read webhooks to know when your message actually lands. Polling /v1/messages/:id works but webhooks are real-time and cheaper. See Webhooks.

Bulk send

POST/v1/messages/bulk

Send up to 100 messages in a single request. Each entry can target a different recipient and use a different line. Per-entry rate limiting applies.

request.json

{
  "messages": [
    { "to": "+15550000001", "body": "Hi Jane" },
    { "to": "+15550000002", "body": "Hi John", "from": "+12138765278" },
    { "to": "+15550000003", "body": "Hi Sam", "effect": "balloons" }
  ]
}

response.json

{
  "results": [
    { "id": "msg_…", "status": "queued", "to": "+15550000001" },
    { "id": "msg_…", "status": "queued", "to": "+15550000002" },
    { "id": "msg_…", "status": "queued", "to": "+15550000003" }
  ],
  "summary": { "queued": 3, "failed": 0 }
}

Multi-line fan-out

POST/v1/messages/multi-line

Send the SAME message from multiple lines to the same recipient. Useful for line warming during ramp-up.

{
  "to": "+15551234567",
  "body": "Test from each line",
  "fromLines": ["+12131111111", "+13105555555", "+18055555555"]
}

Edit a sent message

PUT/v1/messages/:id

Edit a previously-sent iMessage. Apple allows up to 5 edits per message within 15 minutes of sending.

{ "body": "Updated text." }

Edits only render for recipients on iOS 16.4+ / macOS 13.3+. Older devices show the edited message as a new bubble with "Edited to ..." text.

Unsend a message

POST/v1/messages/:id/unsend

Unsend within Apple's 2-minute window. After 2 minutes the message stays. Returns 422 if too late.

Send a reaction (tapback)

POST/v1/messages/:id/react

Add or remove a tapback on any message in a conversation.

{
  "reaction": "love",
  "remove": false
}

Field	Type	Description
`reaction`required	string	One of: `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`.
`remove`	booleandefault `false`	When true, removes an existing reaction instead of adding one.

Show a typing indicator

POST/v1/messages/typing

Show the "…" bubble in the recipient's chat. Useful before a delayed send to feel more natural.

{
  "to": "+15551234567",
  "from": "+12138765278",
  "action": "start"
}

Typing auto-stops when you next send a message or after ~30 seconds, whichever comes first.

Send a read receipt

POST/v1/messages/read

Mark messages from a contact as read. Only fires if read receipts are enabled on the underlying iCloud account.

List messages

GET/v1/messages

Paginated list of messages with filters.

Query parameters

Field	Type	Description
`status`	string	Filter by status: `queued`, `sent`, `delivered`, `read`, `failed`.
`direction`	string	`inbound` or `outbound`.
`to`	string	Filter by recipient (E.164).
`from`	string	Filter by sender line.
`cursor`	string	Pagination cursor from a previous response.
`limit`	integerdefault `50`	Page size. 1-200.

Get a single message

GET/v1/messages/:id

Fetch the latest state of one message by ID.

{
  "id": "msg_pq3z9Vc7BmHkLxQ1aWoZP",
  "status": "read",
  "from": "+12138765278",
  "to": "+15551234567",
  "body": "Your appointment is tomorrow at 2pm.",
  "lineId": "lin_a802426485c04055f82cafd3",
  "sentAt": "2026-05-25T17:23:15.012Z",
  "deliveredAt": "2026-05-25T17:23:15.812Z",
  "readAt": "2026-05-25T17:24:02.331Z",
  "createdAt": "2026-05-25T17:23:14.221Z"
}

Cancel a scheduled message

DELETE/v1/messages/:id/schedule

Cancel a not-yet-sent scheduled message.

iMessage effects reference

Pass any of these as the effect field on a send:

slam

Bubble slams down

loud

Bubble jolts

gentle

Bubble fades softly

invisible

Tap to reveal

balloons

Floating balloons

confetti

Confetti rain

fireworks

Fireworks display

celebration

Falling stars

lasers

Animated lasers

love

Hearts

echo

Bubble echo

spotlight

Spotlight pulse