> ## Documentation Index > Fetch the complete documentation index at: https://docs.bluereacher.com/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Send your first BlueReacher iMessage in five minutes: get an API key, authenticate, send, check status, and receive the reply by webhook. Send your first iMessage through BlueReacher in about five minutes. This page covers what you need, how to authenticate, how to send, how to confirm delivery, and how to catch the reply. ## Before you start You need three things. **An active BlueReacher account.** Any paid plan works. **At least one line.** A line is a dedicated iMessage line, managed for you, with its own phone number in E.164 format. That number becomes the `from` value on every message you send. Your first line is provisioned during onboarding, and no A2P registration required. **An API key.** In your dashboard, open Settings, then API Keys, then Create key. Keys begin with `bluereacher_`. The full value is shown once, so copy it before you close the dialog. ## Authenticate Every endpoint uses the same base URL: ``` https://api.bluereacher.com/functions/v1/ ``` Every request carries two headers: ```bash theme={null} Authorization: Bearer bluereacher_your_api_key Content-Type: application/json ``` Keep the key on your server. Anyone holding it can send from your lines. If a key leaks, revoke it in the dashboard and create a new one. Revocation takes effect immediately. Confirm the key works by listing your lines: ```bash theme={null} curl https://api.bluereacher.com/functions/v1/lines \ -H "Authorization: Bearer bluereacher_your_api_key" ``` ```json theme={null} { "data": [ { "line_id": "line_8fa21c4b", "phone_number": "+14155550142", "status": "active", "created_at": "2026-07-19T15:02:11Z" } ] } ``` Copy the `phone_number` value. That is your `from`. ## Send your first message **Purpose:** queue one outbound message on one of your lines. **Method and path:** `POST https://api.bluereacher.com/functions/v1/messages` **Auth:** `Authorization: Bearer bluereacher_your_api_key` ### Request fields | Field | Type | Required | Description | | ------------- | ------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from` | string | Yes | E.164 number of the line sending the message. Must belong to your account. | | `to` | string | Yes | E.164 number of the recipient. | | `content` | string | Yes, unless `media_url` is set | Message body. Up to 2,000 characters. | | `channel` | string | No | `imessage`, `rcs`, or `sms`. Defaults to `imessage`. | | `media_url` | string | No | Public HTTPS URL to an image, video, or PDF. Up to 100 MB. | | `external_id` | string | No | Your own identifier, up to 128 characters. Echoed back on every webhook for this message. Reusing a value within 24 hours returns the original message instead of sending a duplicate. | ### Example request ```bash theme={null} curl -X POST https://api.bluereacher.com/functions/v1/messages \ -H "Authorization: Bearer bluereacher_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "from": "+14155550142", "to": "+16505550188", "content": "Hey Dana, saw you just opened a second location. Worth a quick chat about how we handle inbound?", "channel": "imessage", "external_id": "lead_4417" }' ``` ### Response fields | Field | Type | Description | | ------------- | -------------- | --------------------------------------------- | | `id` | string | Unique message ID. Use it to check status. | | `status` | string | `queued` on creation. | | `channel` | string | Channel the message was accepted on. | | `from` | string | Sending line number. | | `to` | string | Recipient number. | | `content` | string | Message body as sent. | | `external_id` | string or null | Your identifier, if you supplied one. | | `line_id` | string | ID of the line that owns the send. | | `contact_id` | string | Stable ID for this recipient on your account. | | `created_at` | string | ISO 8601 timestamp in UTC. | ```json theme={null} { "id": "msg_01j9x7ptq3", "status": "queued", "channel": "imessage", "from": "+14155550142", "to": "+16505550188", "content": "Hey Dana, saw you just opened a second location. Worth a quick chat about how we handle inbound?", "external_id": "lead_4417", "line_id": "line_8fa21c4b", "contact_id": "cnt_5d20ab91", "created_at": "2026-07-24T18:41:07Z" } ``` ### Error notes | Code | Meaning | Fix | | ---- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | 401 | Key missing, malformed, or revoked. | Check the `Authorization` header spelling and the key prefix. | | 403 | The `from` number is not a line on your account. | Call `/lines` and use a returned `phone_number`. | | 422 | Validation failed. Common causes: a number that is not E.164, or neither `content` nor `media_url` present. | Read `error.field` in the response body. | | 429 | Rate limit hit. | Wait the number of seconds in the `Retry-After` header, then retry. | ## Check the status `GET https://api.bluereacher.com/functions/v1/messages/{id}` ```bash theme={null} curl https://api.bluereacher.com/functions/v1/messages/msg_01j9x7ptq3 \ -H "Authorization: Bearer bluereacher_your_api_key" ``` ```json theme={null} { "id": "msg_01j9x7ptq3", "status": "delivered", "channel": "imessage", "from": "+14155550142", "to": "+16505550188", "content": "Hey Dana, saw you just opened a second location. Worth a quick chat about how we handle inbound?", "external_id": "lead_4417", "line_id": "line_8fa21c4b", "contact_id": "cnt_5d20ab91", "created_at": "2026-07-24T18:41:07Z" } ``` `status` moves through `queued`, `sent`, `delivered`, and `read`. A message that cannot be delivered ends at `failed` with a `failure_reason` field. Polling works for a one-off test. For production, use webhooks. ## Receive the reply In your dashboard, open Settings, then Webhooks, and add an HTTPS endpoint. Subscribe to `message.received` to get inbound replies, plus `message.delivered` and `message.failed` for outbound results. BlueReacher POSTs JSON to your URL: ```json theme={null} { "event": "message.received", "id": "msg_01j9xa2mk8", "channel": "imessage", "from": "+16505550188", "to": "+14155550142", "content": "Sure, Thursday morning works.", "line_id": "line_8fa21c4b", "contact_id": "cnt_5d20ab91", "status": "received", "created_at": "2026-07-24T18:44:52Z" } ``` On an inbound event, `from` is the contact and `to` is your line. That flip is the fastest way to tell direction. A minimal handler: ```javascript theme={null} app.post("/bluereacher", express.json(), (req, res) => { res.sendStatus(200); const { event, from, content, contact_id } = req.body; if (event === "message.received") { console.log(`Reply from ${from} (${contact_id}): ${content}`); } }); ``` Return a 2xx within 5 seconds. Failed deliveries retry with backoff for 24 hours. Verify the `X-BlueReacher-Signature` header against your signing secret before trusting a payload. ## Next steps * [Sending messages](/api-reference/send-message) covers attachments, long text, and per-channel behavior. * [Channels](/platform/message-formatting) explains how `imessage`, `rcs`, and `sms` differ and when to fall back. * [Webhooks](/api-reference/webhooks) covers the full event list, signature verification, and retry rules. * [Lines](/api-reference/lines) covers adding lines, warmup, and sending volume. * [Messages API reference](/api-reference/messages) documents every field and error code.