Skip to content
Miss Blue

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.

NextReceiving messagesReplies, delivery receipts, and what to do when nothing arrives.