Send a message

POST /v1/messages: send a text and/or media message to one recipient, into an existing group, or to a new group, over the paced drip pipeline or instantly.

POST https://api.bluereacher.com/v1/messages

Requires write permission. Sends iMessage first, with SMS fallback when the recipient cannot take an iMessage.

Choosing the lane

send_mode picks between two pipelines:

drip (default): the paced pipeline. The message is scheduled about 10 minutes out (delay_minutes tunes it) and delivers inside your org-local send window (window_start_hour to window_end_hour, default 9 to 18). Drip sends are spaced, capacity-aware and warm-up aware. Use it for outreach.
instant: dispatches now through the live pipeline. Built for conversational replies. Velocity caps: 10/min and 75/day per key, on top of line-level protections. Requires an online line, otherwise 409 no_online_device. Group sends and message_effect require instant.

Send target

Pass exactly one of:

Field	Meaning
`to`	E.164 recipient for a 1:1 send, for example `+13035550101`
`group_chat_id`	An existing group thread, from `GET /v1/groups` (instant only)
`create_group_phones`	2 to 25 E.164 numbers; creates a new group iMessage, then sends (instant only)

Request fields

Field	Type	Required	Description
`to` / `group_chat_id` / `create_group_phones`		exactly one	See above
`message`	string	unless `media_urls` set	Message text
`media_urls`	array	no	1 to 10 `https://` URLs to attach, max 2048 chars each
`send_mode`	string	no	`drip` (default) or `instant`
`message_effect`	string	no	iMessage effect, instant only: `confetti`, `balloons`, `love`, `lasers`, `fireworks`, `celebration`, `echo`, `spotlight` (full screen); `slam`, `loud`, `gentle`, `invisibleink` (bubble). A drip send with an effect returns `400 effect_requires_instant`
`device_id`	string	no	Explicit line UUID, or `auto_load_balanced` (default) / `auto_round_robin`. Not valid with `group_chat_id`
`delay_minutes`	number	no	Drip only. Minutes from now, default 10
`window_start_hour`	integer	no	Drip only. Earliest org-local delivery hour, default 9
`window_end_hour`	integer	no	Drip only. Latest org-local delivery hour, default 18
`lock`	boolean	no	Lock the contact to the sending line for future sends, default `true`
`metadata`	object	no	Free-form, stored with the send

Send an Idempotency-Key header (max 255 chars). A duplicate request within 24 hours replays the original response with Idempotent-Replay: true instead of double-sending. A concurrent duplicate gets 409 idempotency_conflict.

Example

curl -X POST https://api.bluereacher.com/v1/messages \
  -H "Authorization: Bearer brk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seq-4471-step-1" \
  -d '{
    "to": "+16465550119",
    "message": "Hey Dana, saw you took over ops at Northline. Worth a quick chat?"
  }'

Responses

Discriminate on mode.

Drip queued

{
  "success": true,
  "message_id": "d_1788116691413_milvzs",
  "mode": "drip",
  "queued": true,
  "scheduled_for": "2026-08-31T09:14:51.413Z",
  "estimated_send_time": "2026-08-31T09:14:51.413Z",
  "queue_position": 0
}

Instant dispatched

{
  "success": true,
  "message_id": "i_1788116692980_kulur2",
  "mode": "instant",
  "status": "dispatched",
  "device_id": "8c9a4f2e-1d3b-4a6c-9e8f-2b7c5d1a9e3f"
}

Track delivery with GET /v1/status/{message_id} or, better, the message.sent / message.delivered / message.failed webhooks.

Errors

Status	Code	Meaning
400	`effect_requires_instant`	Effect on a drip send
400	`group_requires_instant`	Group target on a drip send
401	`invalid_api_key`	Bad or revoked key
403	`device_not_owned`	`device_id` outside this workspace
409	`no_online_device`	Instant with no eligible online line
409	`idempotency_conflict`	Same `Idempotency-Key` still in flight
429	`rate_limited`	Wait `retryAfter` seconds

Test mode

With a brk_test_ key the same request validates identically, returns a sim_ message id, sends nothing, and the response carries "sandbox": true.

Send a message

On this page