<!-- https://missblue.dev/docs/sending-messages -->

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.

```bash
curl https://api.missblue.dev/v1/numbers \
  -H "Authorization: Bearer $MISS_BLUE_KEY"
```

```json
{
  "total": 1,
  "data": [
    {
      "id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
      "handle": "+16465550142",
      "label": "Main support",
      "shared": false
    }
  ]
}
```

## 2. Send

```bash
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](https://missblue.dev/docs/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.

```bash
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.

[Next Receiving messages Replies, delivery receipts, and what to do when nothing arrives.](https://missblue.dev/docs/receiving-messages)