Send a message

send-message delivers one message to one recipient. It tries iMessage first, falls back to RCS, then to SMS, and returns immediately with a message id you can track. Use it for one-off sends, CRM-triggered follow-ups, and anything an agent or workflow fires in real time. The call is asynchronous. A 200-class response means BlueReacher accepted the message and queued it, not that the recipient has it. Delivery state arrives on your webhook.

Endpoint

POST https://api.bluereacher.com/functions/v1/send-message

Property	Value
Method	`POST`
Content type	`application/json`
Success status	`202 Accepted` on create, `200 OK` on an idempotent replay
Rate limit	100 requests per minute per workspace

Per-line send pacing is handled for you. Queue as fast as the rate limit allows and BlueReacher spaces the actual sends to protect your line.

Authentication

Every request carries a bearer token:

Authorization: Bearer bluereacher_your_api_key
Content-Type: application/json

Keys start with bluereacher_ and are scoped to one workspace. Create and rotate them in the dashboard under Settings, API keys. Send requests from your server only, never from a browser or mobile client. A missing, malformed, or revoked key returns 401.

Request fields

Field	Type	Required	Description
`to`	string	Yes	The recipient. Either an E.164 phone number (`+14155550142`) or an email address registered with iMessage (`dana@example.com`). Email recipients are iMessage only, so there is no fallback path for them.
`content`	string	Conditional	Message body. Required unless `media_url` is set. Maximum 2,000 characters, UTF-8, emoji allowed.
`media_url`	array of strings	No	Up to 5 public HTTPS URLs to attach. Required if `content` is omitted.
`line_id`	string	No	The dedicated line to send from. Omit it and BlueReacher picks: the line already used with this contact if there is one, otherwise the least-loaded active line in your workspace.
`channel`	string	No	Channel preference: `imessage`, `rcs`, or `sms`. Defaults to `imessage`. Sets where the delivery chain starts, not where it ends. See Channel selection and fallback.
`external_id`	string	No	Your own identifier for this message. Doubles as the idempotency key. Maximum 128 characters. Strongly recommended on every send.
`scheduled_at`	string	No	ISO 8601 timestamp for a future send, with an offset or `Z` (`2026-07-28T14:00:00-05:00`). Between 60 seconds and 90 days from now.
`subject`	string	No	Optional subject line, maximum 128 characters. Does not count toward the 2,000 character `content` limit.

Unknown fields are rejected with 400 rather than ignored, so a typo in a field name fails loudly instead of silently dropping data.

Response fields

Field	Type	Description
`id`	string	BlueReacher message id, prefixed `msg_`. Use it to fetch the message later and to match webhook events.
`status`	string	`queued` for an immediate send, `scheduled` when `scheduled_at` is set.
`channel`	string	The channel the message is queued on: `imessage`, `rcs`, or `sms`. This is the intended channel at queue time. The final channel is confirmed on the `message.sent` webhook.
`to`	string	The recipient, normalized to E.164 when you passed a phone number.
`from`	string	The E.164 number of the line sending this message.
`line_id`	string	The line that will send, whether you set it or BlueReacher selected it.
`external_id`	string or null	Your identifier, echoed back. `null` if you did not send one.
`scheduled_at`	string or null	The scheduled send time in UTC, or `null`.
`created_at`	string	ISO 8601 UTC timestamp of when BlueReacher accepted the request.

Example request

curl -X POST https://api.bluereacher.com/functions/v1/send-message \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550142",
    "content": "Hi Dana, saw you just opened the Austin office. Worth 10 minutes this week?",
    "external_id": "crm_88213-step1"
  }'

With media, a specific line, and a scheduled send:

curl -X POST https://api.bluereacher.com/functions/v1/send-message \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550142",
    "content": "Here is the one-pager we talked about.",
    "media_url": ["https://cdn.example.com/decks/roi-onepager.pdf"],
    "line_id": "line_9f2c41",
    "scheduled_at": "2026-07-28T14:00:00-05:00",
    "external_id": "crm_88213-step2"
  }'

Example response

202 Accepted

{
  "id": "msg_01J8ZC4K2QW3RTY6H9NBVX",
  "status": "queued",
  "channel": "imessage",
  "to": "+14155550142",
  "from": "+16195550188",
  "line_id": "line_9f2c41",
  "external_id": "crm_88213-step1",
  "scheduled_at": null,
  "created_at": "2026-07-24T18:41:07Z"
}

Idempotency with external_id

Set external_id on every send. It is your key for two jobs at once: matching messages back to your own records, and making retries safe. How it behaves:

The first request with a given external_id creates the message and returns 202 with a new id.
Any later request with the same external_id in the same workspace returns the original message body with 200 and the header Idempotent-Replay: true. Nothing is sent twice.
Replaying an external_id with a different request body returns 409 idempotency_conflict. Nothing is sent, and the original message is untouched.
Keys are held for 30 days from first use. After that, the same value creates a new message.
external_id comes back on every webhook for the message, so you can thread replies and delivery events onto your record without storing the BlueReacher id.

Good values are a UUID, or a CRM record id plus the sequence step: crm_88213-step2. Bad values are anything reused across contacts, like the campaign name. Retry 5xx responses, 429, and network timeouts with the exact same body and the same external_id. Use exponential backoff. If the original request landed before the connection dropped, the retry returns the existing message instead of sending a duplicate.

async function sendMessage(payload) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch("https://api.bluereacher.com/functions/v1/send-message", {
      method: "POST",
      headers: {
        "Authorization": "Bearer bluereacher_your_api_key",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });

    // 4xx other than 429 will not succeed on retry. Surface it.
    if (res.status < 500 && res.status !== 429) return res.json();

    await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
  }
  throw new Error("send-message unavailable after 3 attempts");
}

// Same external_id on every attempt, so a retry can never double-send.
sendMessage({
  to: "+14155550142",
  content: "Following up on the Austin note.",
  external_id: "crm_88213-step2"
});

Channel selection and fallback

BlueReacher checks what the recipient can actually receive at send time, then delivers on the best available channel.

Recipient	Channel used	What the recipient gets
iMessage available	`imessage`	Blue bubble, typing indicator, delivered and read receipts
No iMessage, RCS available	`rcs`	Rich formatting and high-resolution media, delivered receipt, read receipt where the carrier reports it
Neither	`sms`	Plain text, MMS when media is attached, delivered receipt where the carrier reports it

The channel field sets where that chain starts. imessage is the default and runs the full chain. rcs skips the iMessage attempt and starts at RCS. sms goes straight to SMS. Fallback always continues downward from wherever you start, so channel narrows the options but never locks the message to one path. Things to know about fallback:

The decision happens at send time, not when you call the API. For a scheduled message, the channel can differ from the channel value in the response if the recipient’s situation changed in between.
The channel in the API response is the intended channel. The message.sent webhook carries the channel that was actually used. Report on the webhook value.
Read receipts exist on iMessage. On RCS and SMS you get delivery state only, and SMS delivery depends on what the carrier reports back.
Media is re-encoded for the channel it lands on. See Character and media limits.
Long messages split into segments on the SMS path. iMessage and RCS send them whole.
iMessage sends are unlimited on your line. RCS and SMS fallback traffic is metered per message and shows up on your workspace usage page.
The iMessage path has no A2P registration required. SMS fallback travels carrier networks, so carrier rules apply to that traffic. SMS fallback is off by default on new workspaces and your account manager turns it on.
To avoid fallback entirely, run the number through the availability check first and only send to iMessage-capable numbers.

If the recipient has opted out, nothing is sent on any channel. STOP keywords are caught automatically and suppressed across your whole workspace, and the request returns 403 recipient_opted_out.

Character and media limits

Text

Limit	Value
`content` maximum	2,000 characters
`subject` maximum	128 characters
Encoding	UTF-8, emoji supported

Over 2,000 characters returns 422 content_too_long with the actual count in the error message. On SMS fallback, text is split into standard segments (160 characters GSM-7, 70 characters when the body contains non-GSM characters such as emoji) and billed per segment. Keep cold outreach under 320 characters and the whole thing stays cheap on every channel. Media

Limit	Value
Attachments per message	5
Size per file	25 MB
Total per message	100 MB
URL scheme	HTTPS only
Fetch timeout	10 seconds per file

Supported types: image/jpeg, image/png, image/gif, image/heic, image/webp, video/mp4, video/quicktime, audio/mpeg, audio/mp4, application/pdf. Anything else returns 422 unsupported_media_type. How media is handled:

Files are fetched server-side at send time. The URL has to be publicly reachable with no auth header. Signed URLs need to stay valid through the send, which for a scheduled message means valid at scheduled_at, not at request time.
content sends first, then attachments in array order, all in the same thread under one message id.
On SMS fallback, attachments become MMS. Files over 1 MB are compressed to fit carrier limits. Anything that cannot be compressed under the cap, such as a PDF, is replaced with a secure link in the message body that stays live for 7 days.
A URL that returns a non-200, times out, or exceeds the size cap returns 422 media_fetch_failed and nothing is sent. Nothing partially delivers.

Scheduling

Set scheduled_at to a future ISO 8601 timestamp and the message holds in the queue until then. status comes back as scheduled instead of queued.

Window: at least 60 seconds and no more than 90 days ahead. Outside that returns 422 invalid_scheduled_at.
Include an offset (-05:00) or Z. A timestamp with no timezone is rejected.
Scheduled sends respect the sending window on the line. If the time lands inside a quiet window, the message goes out at the start of the next allowed window.
Cancel a scheduled message before it fires from the Messages view in the dashboard.
The idempotency rules are identical. A retried schedule request with the same external_id returns the existing scheduled message rather than queuing a second one.

Status values

Status	Meaning
`scheduled`	Accepted and holding for `scheduled_at`.
`queued`	Accepted and waiting on line pacing.
`sent`	Handed off on the channel named in the `message.sent` webhook.
`delivered`	Confirmed on the recipient’s device.
`read`	Recipient opened it. iMessage only, and only when they have read receipts on.
`failed`	Could not be delivered on any available channel. The webhook carries the reason.

Only scheduled and queued ever come back from this endpoint. Everything after that arrives on your webhook.

Errors

Errors return a single error object:

{
  "error": {
    "code": "content_too_long",
    "message": "content is 2,431 characters. The limit is 2,000.",
    "field": "content"
  }
}

Status	Code	What it means
`400`	`invalid_json`	Body is not valid JSON, or contains a field this endpoint does not accept.
`401`	`invalid_api_key`	Key is missing, malformed, or revoked. Check the `Authorization` header format.
`403`	`recipient_opted_out`	The recipient opted out. Nothing was sent and nothing was charged. Do not retry.
`403`	`line_inactive`	The line exists but is paused. Pick another `line_id` or omit the field.
`404`	`line_not_found`	No line with that `line_id` in this workspace.
`409`	`idempotency_conflict`	This `external_id` was already used with a different request body. Nothing was sent.
`422`	`invalid_recipient`	`to` is not valid E.164 and not a valid email address.
`422`	`empty_message`	Neither `content` nor `media_url` was provided.
`422`	`content_too_long`	`content` is over 2,000 characters.
`422`	`too_many_attachments`	More than 5 URLs in `media_url`.
`422`	`media_too_large`	A file is over 25 MB, or the request total is over 100 MB.
`422`	`unsupported_media_type`	The fetched file is not a supported type.
`422`	`media_fetch_failed`	A `media_url` did not return a 200 within 10 seconds, or is not HTTPS.
`422`	`invalid_scheduled_at`	Not ISO 8601, missing a timezone, in the past, under 60 seconds out, or over 90 days out.
`422`	`external_id_too_long`	Over 128 characters.
`429`	`rate_limited`	Over 100 requests per minute. The `Retry-After` header gives the seconds to wait.
`500`	`internal_error`	Something failed on our side. Retry with the same `external_id`.
`503`	`service_unavailable`	Temporary. Retry with backoff and the same `external_id`.

Retry 429, 500, and 503 with the same external_id. Every 4xx other than 429 fails the same way on retry, so fix the request instead.

Next steps

Check whether a number can receive iMessage before you spend a send: Check availability
Catch replies, delivery states, and opt-outs: Webhooks
Background on the platform and what the API covers: iMessage API guide

Messages

Contacts and lines

Automation

Endpoint

Authentication

Request fields

Response fields

Example request

Example response

Idempotency with external_id

Channel selection and fallback

Character and media limits

Scheduling

Status values

Errors

Next steps

​Endpoint

​Authentication

​Request fields

​Response fields

​Example request

​Example response

​Idempotency with external_id

​Channel selection and fallback

​Character and media limits

​Scheduling

​Status values

​Errors

​Next steps

Endpoint

Authentication

Request fields

Response fields

Example request

Example response

Idempotency with external_id

Channel selection and fallback

Character and media limits

Scheduling

Status values

Errors

Next steps