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 person moments apart is refused with 409. 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.