Skip to main content

​
Messages Blocklist

The blocklist is a tenant-owned list of destinations that must never receive your outbound traffic. Open it from Messages → Blocklist in the dashboard. Any destination on the active list — a phone number, an email address, or another channel’s identifier — is rejected at send time across every channel you send on: SMS, MMS, voice, WhatsApp, RCS, Viber, fax, email, telegram, push, messenger, line, and instagram. Use it for the destinations an operator decided to ban: a bad-actor number that keeps drawing complaints, a recipient who asked to be blocked at the account level, or a destination tied to an abuse case. A rejected send returns HTTP 422 with error code CHANNEL_BLOCKED_DESTINATION, before any platform-wide or per-organization prefix layers run — so your entry takes precedence over the broader prefix rules.

​
How the blocklist differs from suppression and opt-outs

Three controls overlap in “stopping messages” but solve different problems:
  • Blocklist (this page) — a hard, operator-managed destination ban. An entry applies to every channel at once, lives until someone removes it, and rejects the send with a 422 the sender has to handle. It is an administrative control, not a compliance record.
  • Message suppression — a content-level duplicate guard. It stops the same body from reaching the same contact twice inside a window; the destination itself stays sendable, and a suppressed send reports as skipped rather than rejected.
  • Opt-outs and suppression lists — the compliance layer. Per-contact opt-out records created by a STOP keyword, a bulk suppression import, or your own sync. These are consent records: they exist because the recipient withdrew consent, not because you banned a destination.
Reach for the blocklist when banning a destination is your decision, driven by operations or abuse response rather than the recipient’s consent flow:
  • Support confirmed a harassment or abuse case and you want that destination cut off everywhere, immediately.
  • An internal review flags a destination your teams must not contact regardless of which campaign or flow tries.
  • You need one place an on-call operator can write to — Messages → Blocklist — without touching compliance records or code.
Reach for opt-outs instead when the recipient initiated the stop (STOP keyword, unsubscribe link, suppression import), because that is the record regulators expect you to honor. Reach for message suppression when the problem is duplicated sends, not the destination.

​
Adding a destination from the dashboard

  1. Open Messages → Blocklist and choose Add destination.
  2. Enter the destination to block:
    • For SMS, MMS, voice, WhatsApp, RCS, Viber, and fax, submit the full E.164 phone number (for example +15551234567). The entry is matched verbatim — it is not a prefix pattern — so it must be the complete number.
    • For email, telegram, push, messenger, line, and instagram, submit that channel’s native destination identifier (for example the email address or chat id).
  3. Optionally record a reason — the support ticket or abuse-case reference — so the next reviewer knows why the entry exists.
  4. Choose Block destination. The entry takes effect immediately: the next outbound send to that destination on any channel is rejected.
Destinations are limited to 254 characters and reasons to 500. If the destination is already on the active list the dashboard surfaces the API’s 409 BLOCKED_NUMBER_ALREADY_EXISTS rather than creating a duplicate row. Only members with the owner, admin, or developer role can add or remove entries; viewers see the page without the write affordances. This mirrors the API’s write guard, so there is no way around it through the dashboard.

​
Removing an entry

Choose the delete action on a row and confirm. The destination becomes send-eligible immediately — outbound sends across every channel start reaching it again until you re-block. Removal is soft: the row remains in the list’s history (visible to API callers that request deleted entries) rather than vanishing, so an audit question about “when was this destination un-blocked” has an answer.

​
Adding entries in bulk

There is one active-list operation per destination, so a bulk onboarding — importing a blocklist from a previous platform, for example — loops over the POST /api/v1/messages/blocklist endpoint:
Keep the reason on every import row. A blocklist imported without reasons becomes un-auditable the moment the importing operator leaves. The full endpoint set is: GET returns active entries by default. Pass include_deleted=true to audit removed entries — each removed entry keeps its row with a removal timestamp instead of being erased.

​
Where blocked sends appear

A blocked send never reaches the provider, so there is nothing to trace on the provider side — the trace lives in Orbit instead:
  • The send call itself. A single-send API call to a blocked destination returns HTTP 422 with code CHANNEL_BLOCKED_DESTINATION. Handle it as a permanent rejection for that destination, not a retryable error.
  • Batch sends. When you bulk-send to a list that includes a blocked destination, only that recipient fails: its outcome row reports CHANNEL_BLOCKED_DESTINATION and the response comes back HTTP 207 (Multi-Status) if the rest succeeded. See the batch SMS guide for the outcome-map shape.
  • Delivery log. Dashboard-initiated sends record their outcome as they go through the send pipeline, so a blocked attempt shows as a failed message rather than a delivered one. Use the delivery log to answer “did we actually stop sending to this destination after the block went in?” — every attempted send after the block timestamps its rejection.

​
Governing the list

The blocklist is cheap to write to and strong when active, so give it an owner:
  • Who manages it. Because writes are guarded to owner, admin, and developer roles, most teams operate the blocklist as an on-call or trust-and-safety responsibility: anyone in those roles can add an entry during an incident, but the reason field is mandatory team practice even though the API treats it as optional.
  • Review cadence. The active list is small by nature — if your blocklist grows into the hundreds, that is a signal the entries should be living in an opt-out or compliance flow instead. Review the list on a fixed cadence (monthly is common), check each entry has a reason, and remove entries whose originating case is resolved.
  • Audit removals. Removals are soft deletes; a periodic review against include_deleted=true answers “who un-blocked what, and when” without leaving the API.
Entries rejected on a transient backend problem — not a validation failure — are the one thing to watch on this page: if loading the list fails, the page tells you and retries, and the send-path block check fails open rather than blocking your outbound traffic. A blocklist that cannot be read never silently stops sends.

​
See also