Opt-out handling

Every inbound message on your account is checked for opt-out intent before it reaches your webhook. When a contact opts out, the suppression takes effect immediately and applies to your entire account. No line can message that contact again until you clear it. This page covers what triggers an opt-out, what happens the moment one lands, the contact.opted_out webhook event, the two endpoints for syncing suppression with your own systems, and why enforcement happens at send time instead of at list-build time.

What triggers an opt-out

BlueReacher runs two checks on every inbound message. Keyword match. Case-insensitive, punctuation-tolerant, whitespace-trimmed. A reply is a keyword opt-out when the whole message, after stripping punctuation and emoji, matches one of these:

Keyword	Also matches
STOP	`stop`, `Stop.`, `STOP!`, `stop`
STOPALL	`stop all`, `stopall`
UNSUBSCRIBE	`unsubscribe`, `Unsubscribe.`
END	`end`
QUIT	`quit`
CANCEL	`cancel`
OPTOUT	`opt out`, `opt-out`
REVOKE	`revoke`

Plain-language match. Most people do not type STOP. They write a sentence. Every inbound reply is classified for removal intent and the contact is suppressed when the message is a removal request, whatever the wording. These suppress:

“please take me off your list”
“don’t text me again”
“how did you get this number, remove me”
“stop messaging me, I’m not interested”
“unsubscribe me from whatever this is”
“keep texting and I’m reporting this”

These do not suppress:

“stop by the office next week” (keyword inside a sentence, not the whole message)
“we’re looking to stop using our current vendor” (same)
“not interested” (a soft no, classified as a negative reply, not a removal request)
“who is this?”

Soft negatives arrive on the inbound webhook with a negative classification and leave the contact sendable. If your policy is to suppress every negative reply, do that yourself by calling set-opt-out from your reply handler.

What happens the moment a contact opts out

In order, within the same second the reply is processed:

The contact is marked opted_out: true with a timestamp and a source.
Every queued and scheduled message addressed to that contact is cancelled, on every line, in every campaign, and moves to status: "rejected".
The contact.opted_out webhook fires.
Any new send addressed to that contact is refused at the API with 403.

Suppression is scoped to your account, not to a line and not to a channel. A contact who opts out on one of your dedicated iMessage lines cannot be reached from any other line on the account, including lines added later, and cannot be reached on imessage, rcs, or sms. The identity being suppressed is the phone number. A refused send returns:

{
  "status": "rejected",
  "error": {
    "code": "contact_opted_out",
    "message": "Contact +15125550142 opted out at 2026-07-24T15:04:10Z. No line on this account can message this contact.",
    "contact_id": "cnt_8f21ab90",
    "opted_out_at": "2026-07-24T15:04:10Z"
  }
}

Branch on error.code, not on the message string. The code is stable, the message is not.

The contact.opted_out webhook

Subscribe in the dashboard under Webhooks. The event fires once per opt-out, whether it came from detection, the API, or a dashboard action.

{
  "event": "contact.opted_out",
  "created_at": "2026-07-24T15:04:11Z",
  "data": {
    "contact_id": "cnt_8f21ab90",
    "to": "+15125550142",
    "line_id": "line_4a7c9e",
    "channel": "imessage",
    "source": "plain_language",
    "content": "please take me off your list",
    "external_id": "lead_88213",
    "opted_out_at": "2026-07-24T15:04:10Z",
    "cancelled_messages": 3
  }
}

Field	Type	Description
`contact_id`	string	BlueReacher identifier for the contact.
`to`	string	The suppressed number in E.164. In every opt-out payload, `to` is the contact, never your line.
`line_id`	string	The line the opt-out arrived on. Informational only. Suppression is account-wide.
`channel`	string	`imessage`, `rcs`, or `sms`. The channel the reply came in on.
`source`	string	`keyword`, `plain_language`, `api`, or `dashboard`.
`content`	string	The message that triggered detection. `null` when `source` is `api` or `dashboard`.
`external_id`	string	Your identifier for the contact, if you set one at send or import time.
`opted_out_at`	string	ISO 8601 UTC timestamp of the suppression.
`cancelled_messages`	integer	Queued or scheduled messages cancelled for this contact.

Two rules for the handler. Write the suppression to your system of record in the same run, because this event is the only push signal you get. And deduplicate on contact_id, because webhook delivery is at-least-once and a retry will arrive with an identical payload.

set-opt-out

Push a suppression from your own systems into BlueReacher, or clear one you added by mistake. Use it when someone unsubscribes by email, tells a rep on a call, or gets flagged Do Not Contact in your CRM. POST https://api.bluereacher.com/functions/v1/set-opt-out Auth uses the same key as sending: Authorization: Bearer bluereacher_your_api_key. There is no separate compliance scope.

Field	Type	Required	Description
`to`	string	Yes, unless `contact_id` is set	Phone number in E.164.
`contact_id`	string	Yes, unless `to` is set	BlueReacher contact identifier.
`opted_out`	boolean	Yes	`true` suppresses, `false` clears.
`source`	string	No	Free-form label up to 64 characters, stored on the record. Use it to trace where the suppression came from.
`external_id`	string	No	Your identifier for this contact. Written to the contact if not already set.
`confirm_consent`	boolean	Conditional	Required when setting `opted_out: false` on a contact suppressed by `keyword` or `plain_language`.

curl -X POST https://api.bluereacher.com/functions/v1/set-opt-out \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15125550142",
    "opted_out": true,
    "source": "hubspot_dnc_sync",
    "external_id": "lead_88213"
  }'

{
  "contact_id": "cnt_8f21ab90",
  "to": "+15125550142",
  "opted_out": true,
  "source": "hubspot_dnc_sync",
  "external_id": "lead_88213",
  "opted_out_at": "2026-07-24T15:04:10Z",
  "cancelled_messages": 0,
  "status": "updated",
  "created_at": "2026-06-02T18:22:41Z"
}

Field	Type	Description
`contact_id`	string	Contact identifier. Created if the number was not on your account yet.
`to`	string	Normalized E.164 number.
`opted_out`	boolean	State after the call.
`source`	string	The label you sent, or the existing source if the state did not change.
`external_id`	string	Your identifier, or `null`.
`opted_out_at`	string	Timestamp of the suppression, or `null` when `opted_out` is `false`.
`cancelled_messages`	integer	Queued messages cancelled by this call.
`status`	string	`updated` or `unchanged`.
`created_at`	string	When the contact record was first created.

Errors:

Status	Code	Meaning
400	`invalid_phone_number`	`to` is not parseable as E.164.
400	`missing_field`	Neither `to` nor `contact_id` was sent, or `opted_out` is absent.
401	`invalid_api_key`	Key missing, malformed, or revoked.
409	`consent_confirmation_required`	You tried to clear a detected opt-out without `confirm_consent: true`.
429	`rate_limited`	Over 120 requests per minute on this key. Retry after the `Retry-After` header.

Clearing a detected opt-out is allowed, and it is logged with the API key that did it and a timestamp. Do it only when you hold a record of new consent. BlueReacher does not evaluate that record. You own it.

check-opt-out

Read suppression state for a batch of numbers before you import them or open a send window. It creates nothing, changes nothing, and does not count against send volume. POST https://api.bluereacher.com/functions/v1/check-opt-out Auth header is the same: Authorization: Bearer bluereacher_your_api_key.

Field	Type	Required	Description
`to`	array of strings	Yes	1 to 1,000 phone numbers in E.164.
`include_source`	boolean	No	Default `false`. When `true`, each result carries `source` and `opted_out_at`.

curl -X POST https://api.bluereacher.com/functions/v1/check-opt-out \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+15125550142", "+14155550188", "+12065550119"],
    "include_source": true
  }'

{
  "results": [
    {
      "to": "+15125550142",
      "contact_id": "cnt_8f21ab90",
      "opted_out": true,
      "opted_out_at": "2026-07-24T15:04:10Z",
      "source": "keyword"
    },
    {
      "to": "+14155550188",
      "contact_id": "cnt_2b7710de",
      "opted_out": false,
      "opted_out_at": null,
      "source": null
    },
    {
      "to": "+12065550119",
      "contact_id": null,
      "opted_out": false,
      "opted_out_at": null,
      "source": null
    }
  ],
  "invalid": [],
  "checked_at": "2026-07-24T16:11:03Z"
}

Field	Type	Description
`results`	array	One entry per valid number, in the order you submitted them.
`results[].to`	string	Normalized E.164 number.
`results[].contact_id`	string	Contact identifier, or `null` if the number has never been on your account.
`results[].opted_out`	boolean	Current suppression state.
`results[].opted_out_at`	string	Timestamp, or `null`. Present only when `include_source` is `true`.
`results[].source`	string	`keyword`, `plain_language`, `api`, or `dashboard`. Present only when `include_source` is `true`.
`invalid`	array of strings	Numbers that failed E.164 parsing. They are skipped, not fatal.
`checked_at`	string	ISO 8601 UTC timestamp of the read.

Errors:

Status	Code	Meaning
400	`invalid_request`	`to` is missing, empty, or not an array.
401	`invalid_api_key`	Key missing, malformed, or revoked.
422	`too_many_contacts`	More than 1,000 numbers in one call. Split the batch.
429	`rate_limited`	Over 60 requests per minute on this key.

A contact_id of null with opted_out: false means no opt-out is on file. That is not the same as consent. It only tells you this number has not asked you to stop.

Cleaning a list before import

Normalize every number to E.164 before you send it. Numbers that fail parsing land in invalid and get silently skipped, which reads as a clean list when it is not.
Deduplicate. Duplicate numbers burn batch slots and produce duplicate results.
Split into batches of 1,000 and call check-opt-out on each.
For every hit, write the suppression back to the source system. Dropping the row from your CSV loses the reason.
Import the remainder.

The check is a snapshot taken at checked_at. A list cleaned Monday and sent Thursday is three days stale. The running webhook handler is what covers that gap, not the import-time check.

Why enforcement happens at send time

Filtering at list-build time is the obvious design: clean the list, then send it. It breaks in four predictable ways. Lists go stale. An opt-out that lands at 10:02 does nothing to a list filtered at 09:00. The larger your campaign, the longer the window between build and last send, and the more messages go out to people who already asked you to stop. Opt-outs are account-wide, lists are not. A contact who opts out on one line is usually sitting in three other lists for other campaigns on other lines. Filtering per list means every list has to learn about every opt-out independently. One missed sync is a message you cannot take back. Scheduled and multi-step sends fire later. Follow-ups, drips, and retries execute hours or days after the list was assembled. A build-time filter cannot see a decision the contact makes in between. Failure directions are not equal. A list-time filter that misses someone fails open: the message ships and you learn about it from the recipient. A send-time check that misbehaves fails closed: the send is refused, you see a 403 in your logs, and you can fix it. A refused send is recoverable. A delivered one is not. Send-time enforcement also preserves the record. Deleting suppressed people from your list destroys your evidence that you honored the request. Keeping the contact with opted_out, opted_out_at, and source means you can show exactly when someone asked you to stop and what happened next. The tradeoff is real and you have to code for it. Your queued count will not match your delivered count, and 403 contact_opted_out is a normal outcome rather than an exception. Treat it as terminal. Retrying it never succeeds.

Checklist

Handle contact.opted_out and write to your system of record in the same run. Deduplicate on contact_id.
Treat 403 contact_opted_out as a terminal state. No retry, no backoff.
Run check-opt-out on every list before import, in batches of 1,000, on normalized E.164 numbers.
Push CRM, email, and phone unsubscribes into set-opt-out on a schedule, not only at import time.
Never clear a detected opt-out without a consent record you can produce on request.

Getting started

Integrations

Platform

What triggers an opt-out

What happens the moment a contact opts out

The contact.opted_out webhook

set-opt-out

check-opt-out

Cleaning a list before import

Why enforcement happens at send time

Checklist

​What triggers an opt-out

​What happens the moment a contact opts out

​The contact.opted_out webhook

​set-opt-out

​check-opt-out

​Cleaning a list before import

​Why enforcement happens at send time

​Checklist

What triggers an opt-out

What happens the moment a contact opts out

The contact.opted_out webhook

set-opt-out

check-opt-out

Cleaning a list before import

Why enforcement happens at send time

Checklist