Quickstart

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:

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:

curl https://api.bluereacher.com/functions/v1/lines \
  -H "Authorization: Bearer bluereacher_your_api_key"

{
  "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

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.

{
  "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}

curl https://api.bluereacher.com/functions/v1/messages/msg_01j9x7ptq3 \
  -H "Authorization: Bearer bluereacher_your_api_key"

{
  "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:

{
  "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:

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 covers attachments, long text, and per-channel behavior.
Channels explains how imessage, rcs, and sms differ and when to fall back.
Webhooks covers the full event list, signature verification, and retry rules.
Lines covers adding lines, warmup, and sending volume.
Messages API reference documents every field and error code.

Getting started

Integrations

Platform

Before you start

Authenticate

Send your first message

Request fields

Example request

Response fields

Error notes

Check the status

Receive the reply

Next steps

​Before you start

​Authenticate

​Send your first message

​Request fields

​Example request

​Response fields

​Error notes

​Check the status

​Receive the reply

​Next steps

Before you start

Authenticate

Send your first message

Request fields

Example request

Response fields

Error notes

Check the status

Receive the reply

Next steps