Getting started
Sending messages
Two calls: find the number you are sending from, then send.
1. Find your number
A key can hold more than one line, so a send always names which. The Mac behind a number is never returned — which machine holds a line is our problem, and telling you would make it yours.
curl https://api.missblue.dev/v1/numbers \
-H "Authorization: Bearer $MISS_BLUE_KEY"{
"total": 1,
"data": [
{
"id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
"handle": "+16465550142",
"label": "Main support",
"shared": false
}
]
}2. Send
curl -X POST https://api.missblue.dev/v1/messages \
-H "Authorization: Bearer $MISS_BLUE_KEY" \
-H "Content-Type: application/json" \
-d '{
"number_id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
"recipient": "+15555550100",
"text": "Your table is confirmed for 7pm."
}'What “accepted” means
A 201 means we have it, not that it has arrived. Between here and a phone there is a Mac, Apple, and a network, and none of them answer synchronously.
queued: true means it has not left yet. Sending is paced per number so a burst does not look like spam to Apple — a hundred messages posted at once are accepted at once and go out over the following minutes. This is deliberate, and it is why a delivery receipt is a separate event rather than a field on this response.
To learn what happened next, read Receiving messages.
Sending a file
Upload first, then send the id. iMessage has no notion of a caption — the platform takes text or a file, never both — so text and attachments go as separate messages rather than one being silently dropped.
ATTACHMENT=$(curl -s -X POST https://api.missblue.dev/v1/attachments \
-H "Authorization: Bearer $MISS_BLUE_KEY" \
-H "Content-Type: image/png" \
-H "X-Miss-Blue-File-Name: receipt.png" \
--data-binary @receipt.png | jq -r .id)
curl -X POST https://api.missblue.dev/v1/messages \
-H "Authorization: Bearer $MISS_BLUE_KEY" \
-H "Content-Type: application/json" \
-d "{\"number_id\": \"$NUMBER\",
\"recipient\": \"+15555550100\",
\"attachment_ids\": [\"$ATTACHMENT\"]}"Sending into an existing conversation
Pass a chat_id as the recipient. This is also how you send to a group: a group has a chat id like any other conversation, and the call is the same.
Sending the same thing twice
The same text to the same conversation — by number, chat id or thread id — is refused with 409 for 30 seconds, and for 10 minutes when the first copy has not gone yet or the text is long (80 characters or more) or carries a link. The refusal's error.message_id is the original. Retries after a timeout are the usual cause, and a customer receiving your message twice is a worse outcome than a send you have to repeat on purpose. Pass allow_duplicate when you mean it.
allow_duplicate does not override an identical copy while the first is still being sent (pending, for up to five minutes): wait for its message.sent or message.failed instead of sending again.