Send a group message

Send one message to an iMessage group thread. Pass group_id to post into a thread that already exists, or pass a participants array to create a new group and send its first message in the same call. Group threads are iMessage only. There is no SMS fallback for a group.

Endpoint

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

Item	Value
Method	`POST`
Base URL	`https://api.bluereacher.com/functions/v1/`
Path	`send-group-message`
Content-Type	`application/json`
Success status	`200 OK`

Authentication

Every request needs your API key in the Authorization header as a bearer token. Keys start with bluereacher_.

Authorization: Bearer bluereacher_your_api_key

Keys are scoped to your workspace and can send from any active line in it. Keep keys server side. A key in browser or mobile client code can send from your lines.

Two modes

Send exactly one of group_id or participants. Sending both returns 400 invalid_request. Sending neither returns the same error.

Mode	You send	What happens
Send to an existing group	`group_id`	The message posts into that thread. No membership changes.
Create and send	`participants`	BlueReacher creates the group, sends your message as the first one in it, and returns the new `group_id`.

Store the group_id from the response. It is the only handle that ties your outbound group messages to the inbound replies that come back from that thread.

Request fields

Field	Type	Required	Description
`from`	string	Yes, unless `line_id` is set	The dedicated iMessage line sending the message, in E.164 format, for example `+14155550142`.
`line_id`	string	Yes, unless `from` is set	The line identifier from your dashboard, for example `line_01J8ZC4K2Q`. Use this instead of `from` if you rotate numbers.
`group_id`	string	Yes, if `participants` is absent	An existing thread, for example `grp_01J9F2Q7X4T9`. Must belong to the same line.
`participants`	array of strings	Yes, if `group_id` is absent	2 to 24 recipient addresses in E.164 format, or Apple ID email addresses. Your own line is added automatically.
`content`	string	Yes, unless `media_url` is set	Message body. Up to 4,000 characters.
`media_url`	string or array of strings	No	One URL, or up to 5 URLs, each publicly reachable over HTTPS and up to 25 MB. Sent as attachments in the thread.
`group_name`	string	No	Names the thread for every participant. Up to 64 characters. Accepted only when creating a group.
`channel`	string	No	Only `"imessage"` is valid here. Passing `"sms"` or `"rcs"` returns `400 invalid_channel`. Omit it and the group defaults to `imessage`.
`external_id`	string	No	Your own message reference, up to 64 characters. Doubles as the idempotency key: the same `external_id` inside 24 hours returns the original message instead of sending a second one. If you omit it, BlueReacher generates one.
`contact_id`	string	No	A BlueReacher contact ID to attribute the send to in reporting. Does not change who receives the message.

Group limits

These are the documented defaults on every plan.

Limit	Value
Participants per group	25, counting your line
`participants` array on create	2 to 24 addresses
Group name	64 characters
Message body	4,000 characters
Attachments per message	5, up to 25 MB each
New groups per line	25 per hour
Rate limit cost	One group message counts as one send, whatever the participant count
Membership after creation	Fixed. Members cannot be added or removed through the API.

Hit the group creation cap and the API returns 429 rate_limit_exceeded with a retry_after value in seconds. Sends into existing groups keep working while that cap is in effect.

Who you can add

Participants have to clear four checks before the group is created. The checks run on the whole array first, so a bad address means nothing is sent and no group exists.

iMessage-capable. Every address must be reachable on iMessage. Run your list through the availability check endpoint before you build the array, and drop anything that comes back unavailable.
Not opted out. Any address suppressed by a STOP keyword or a manual opt-out is rejected. A participant who replies STOP inside a group is suppressed across your workspace and excluded from future group sends.
Valid format. E.164 phone numbers such as +14155550188, or Apple ID email addresses such as sam@example.com. Anything else is rejected.
Distinct. Duplicates are collapsed to one entry. Your sending line is removed from the array if you include it, then added back as the sender, so it never eats one of your 24 slots.

Membership is set once, at creation. To message a different set of people, create a new group. If a participant leaves the thread on their own, the group_id stays valid and later sends reach whoever is left. If every participant leaves, sends to that group_id return 422 group_empty.

iMessage only, no SMS fallback

One-to-one sends through /send-message fall back to RCS, then SMS, when a number cannot receive iMessage. Group sends do not. A group thread is an iMessage object, so there is no green-bubble equivalent to fall back to and no per-participant downgrade. What that means in practice:

If any address in participants cannot receive iMessage, the request fails with 422 participant_not_imessage, the response lists the failing addresses, and no group is created.
The channel field on the response is always imessage.
To reach a non-iMessage number, send it a one-to-one message through /send-message and let the fallback chain handle it.

Filter first, send second. Checking availability before you build the array turns a failed request into a clean group.

Response fields

Field	Type	Description
`external_id`	string	Message identifier. Yours if you supplied one, otherwise generated, for example `msg_01J9F2Q7XK4B`. Echoed on every webhook for this message.
`group_id`	string	Thread identifier. Store it to send again or to match inbound replies.
`group_created`	boolean	`true` when this call created the thread, `false` when it posted into an existing one.
`group_name`	string or null	Thread name, or `null` if you did not set one.
`from`	string	The line that sent the message, in E.164 format.
`line_id`	string	Identifier of that line.
`to`	array of strings	Every participant in the thread, excluding your line.
`channel`	string	Always `imessage` for group sends.
`content`	string or null	The message body as sent.
`media_url`	array of strings or null	Attachments accepted for this message.
`status`	string	`queued`, `sent`, `delivered`, or `failed`. Fresh sends come back as `queued`.
`created_at`	string	ISO 8601 timestamp in UTC.

Group status is reported per message, not per participant. delivered means the thread accepted the message. Read receipts are not broken out by participant on group threads.

Create a group and send

curl -X POST https://api.bluereacher.com/functions/v1/send-group-message \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155550142",
    "participants": ["+14155550188", "+16505550119"],
    "group_name": "Acme rollout",
    "content": "Hey both, putting us in one thread so nothing gets crossed. Does Thursday 10am PT work for the walkthrough?",
    "external_id": "acme-rollout-intro-01"
  }'

Response:

{
  "external_id": "acme-rollout-intro-01",
  "group_id": "grp_01J9F2Q7X4T9",
  "group_created": true,
  "group_name": "Acme rollout",
  "from": "+14155550142",
  "line_id": "line_01J8ZC4K2Q",
  "to": ["+14155550188", "+16505550119"],
  "channel": "imessage",
  "content": "Hey both, putting us in one thread so nothing gets crossed. Does Thursday 10am PT work for the walkthrough?",
  "media_url": null,
  "status": "queued",
  "created_at": "2026-07-24T18:42:07Z"
}

Send to an existing group

curl -X POST https://api.bluereacher.com/functions/v1/send-group-message \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155550142",
    "group_id": "grp_01J9F2Q7X4T9",
    "content": "Sending the one-pager over now.",
    "media_url": "https://cdn.example.com/acme/one-pager.pdf"
  }'

Response:

{
  "external_id": "msg_01J9F30C6M2P",
  "group_id": "grp_01J9F2Q7X4T9",
  "group_created": false,
  "group_name": "Acme rollout",
  "from": "+14155550142",
  "line_id": "line_01J8ZC4K2Q",
  "to": ["+14155550188", "+16505550119"],
  "channel": "imessage",
  "content": "Sending the one-pager over now.",
  "media_url": ["https://cdn.example.com/acme/one-pager.pdf"],
  "status": "queued",
  "created_at": "2026-07-24T18:47:19Z"
}

Keep the group_id and reuse it

const BASE = "https://api.bluereacher.com/functions/v1/";
const headers = {
  Authorization: "Bearer bluereacher_your_api_key",
  "Content-Type": "application/json",
};

async function sendGroup(body) {
  const res = await fetch(`${BASE}send-group-message`, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
  return data;
}

// 1. Create the thread and send the opener.
const opener = await sendGroup({
  from: "+14155550142",
  participants: ["+14155550188", "+16505550119"],
  group_name: "Acme rollout",
  content: "Hey both, one thread for the rollout. Thursday 10am PT work?",
});

await db.deals.update(dealId, { group_id: opener.group_id });

// 2. Follow up later in the same thread.
await sendGroup({
  from: "+14155550142",
  group_id: opener.group_id,
  content: "Calendar invite is out, see you Thursday.",
});

Replies and events

Inbound group replies POST to your webhook URL with the group_id attached, so you can thread them against the right deal. from is the individual who replied. to is your line.

{
  "external_id": "msg_01J9F31RB8QD",
  "group_id": "grp_01J9F2Q7X4T9",
  "from": "+16505550119",
  "to": "+14155550142",
  "contact_id": "con_01J8ZD9M7P",
  "channel": "imessage",
  "content": "Thursday works for me.",
  "created_at": "2026-07-24T18:51:33Z"
}

Status changes for outbound group messages arrive on the same webhook with the message external_id and the new status. A group message reports one status for the thread, so track state at the message level, not per participant.

Errors

Errors return a JSON body with an error object. Nothing is sent when a request fails validation, including partial group creation.

{
  "error": {
    "code": "participant_not_imessage",
    "message": "2 participants cannot receive iMessage. No group was created and no message was sent.",
    "participants": ["+13125550164", "+13235550110"]
  }
}

Status	Code	Meaning and fix
400	`invalid_request`	Malformed JSON, or both `group_id` and `participants` sent, or neither. Send exactly one.
400	`invalid_channel`	`channel` was set to something other than `imessage`. Groups are iMessage only.
400	`group_name_locked`	`group_name` was sent with `group_id`. Names are set at creation.
400	`missing_content`	Neither `content` nor `media_url` was present. Send at least one.
401	`invalid_api_key`	Key missing, malformed, or revoked. Check the `Authorization` header.
403	`line_not_active`	The line in `from` or `line_id` is not active on your workspace. Check the dashboard.
404	`group_not_found`	Unknown `group_id`, or it belongs to a different line. Send from the line that created the group.
413	`media_too_large`	An attachment is over 25 MB, or you sent more than 5.
422	`participant_not_imessage`	One or more addresses cannot receive iMessage. Failing addresses are listed in `participants`.
422	`participant_opted_out`	One or more addresses are suppressed. Remove them and resend.
422	`too_many_participants`	More than 24 addresses in `participants`. The thread cap is 25 including your line.
422	`too_few_participants`	Fewer than 2 addresses. Use `/send-message` for one-to-one.
422	`invalid_participant_format`	An address is not E.164 or a valid Apple ID email.
422	`group_empty`	Every participant has left the thread. Create a new group.
429	`rate_limit_exceeded`	Line send rate or the 25 new groups per hour cap. Retry after `retry_after` seconds.
500	`internal_error`	Send failed on our side. Retry with the same `external_id`, which is safe because it deduplicates.

Practical notes

Group sends are for conversations with people who already know you, like a buyer and their colleague, or a rep, an AE, and a prospect. Cold group blasts read as spam and get reported as spam.
Keep threads small. Three to five people holds a conversation. Twenty turns into noise, and one STOP from anyone in it suppresses that contact everywhere.
Consent is per person. Every participant needs a lawful basis to be messaged, the same as any one-to-one send.
Lines are dedicated iMessage lines, managed for you, so no A2P registration required for group iMessage traffic. Any SMS traffic you send on other paths still carries its own registration requirements.

Messages

Contacts and lines

Automation

Endpoint

Authentication

Two modes

Request fields

Group limits

Who you can add

iMessage only, no SMS fallback

Response fields

Create a group and send

Send to an existing group

Keep the group_id and reuse it

Replies and events

Errors

Practical notes

​Endpoint

​Authentication

​Two modes

​Request fields

​Group limits

​Who you can add

​iMessage only, no SMS fallback

​Response fields

​Create a group and send

​Send to an existing group

​Keep the group_id and reuse it

​Replies and events

​Errors

​Practical notes

Endpoint

Authentication

Two modes

Request fields

Group limits

Who you can add

iMessage only, no SMS fallback

Response fields

Create a group and send

Send to an existing group

Keep the group_id and reuse it

Replies and events

Errors

Practical notes