> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound Blocklist API

> Manage the do-not-contact list that stops sequences from reaching an address on any channel. Use to honour opt-outs from your own systems and to sync consent.

The outbound blocklist is the organization's **do-not-contact list**. An address on it is never contacted by a sequence: the engine checks the list when people are enrolled, when a sequence launches, and again before every single send. If the list cannot be read, the send is held rather than released.

<Note>
  This is not the [Blocklist API](/api-reference/blocklist/index). That one is **inbound**: it stops the AI from replying to a visitor who messages you. This one is **outbound**: it stops you reaching out. They answer different questions and share no storage.
</Note>

## What an entry is

Entries are keyed on the **address**, not on a contact record, so consent survives the contact being merged, deleted or re-imported.

| Field            | Meaning                                                                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identity_type`  | `phone`, `email` or `whatsapp_user_id`.                                                                                                                                                   |
| `identity_value` | The address as stored after normalization: phone numbers in international format, emails lowercased.                                                                                      |
| `channel`        | Which channel the entry covers. `null` means every channel; entries added through this API are always `null`. A specific channel appears when the person opted out of that channel alone. |
| `reason`         | Why the address was blocked. Free text for your own auditing on entries you add.                                                                                                          |
| `source`         | Where the entry came from. `api` is one you added. Anything else was recorded when the person opted out themselves, or when their address bounced.                                        |
| `expires_at`     | When the block lifts automatically. `null` means never.                                                                                                                                   |

### Who else writes entries

The list is shared with the channels themselves. Besides what you add, entries appear when:

* a person opts out of WhatsApp marketing messages (`channel: whatsapp`),
* a person unsubscribes from an email through the unsubscribe link or one-click header (`channel: email`),
* an email address hard-bounces (`channel: email`).

Those entries carry a `source` other than `api`. [List](/api-reference/outbound-blocklist/list) returns all of them so a sync into your CRM sees everything.

## How channels are covered

A block applies to every channel that could reach the address:

| Blocked identity   | Stops                                                                 |
| ------------------ | --------------------------------------------------------------------- |
| `phone`            | WhatsApp messages and phone calls to that number.                     |
| `whatsapp_user_id` | WhatsApp messages to that account. Says nothing about calls or email. |
| `email`            | Email to that address. Says nothing about WhatsApp or calls.          |

Someone reachable on WhatsApp without a known phone number is a separate identity: if you hold both a phone and a WhatsApp user id for a person, block both.

A person is skipped at enrollment only when every channel they could be reached on is blocked. A block on one channel leaves them enrollable, and the launch and send gates hold them on that channel only.

## Rules

* **Blocking is idempotent and only strengthens.** Re-blocking an existing address never shortens its expiry and never turns a permanent block into a temporary one. Retrying a queued job is harmless.
* **`expires_at` must be in the future.** Omit it for a permanent block.
* **Unblocking defaults to your own entries.** [Unblock](/api-reference/outbound-blocklist/unblock) removes entries with `source: api` that cover every channel. A person's own opt-out and single-channel entries are left in place and counted in `skipped`. When `skipped` is above zero the address is still blocked; pass `include_provider_entries=true` to remove those too, deliberately.
* **Check ignores expired entries.** [Check](/api-reference/outbound-blocklist/check) answers `blocked` when at least one live entry exists and returns them, so you can see which channel each covers.
* **Invalid addresses are rejected**, never stored as-is, so junk can never occupy an address's slot.

## Scopes

Entries govern outbound sending, so the endpoints use the sequence scopes: `sequences:write` to block and unblock, `sequences:read` to check and list.

## Available endpoints

<CardGroup cols={2}>
  <Card title="Block address" icon="user-slash" href="/api-reference/outbound-blocklist/block">Add a phone, email or WhatsApp user id</Card>
  <Card title="Unblock address" icon="user-check" href="/api-reference/outbound-blocklist/unblock">Remove an address, with skipped reporting</Card>
  <Card title="Check address" icon="magnifying-glass" href="/api-reference/outbound-blocklist/check">Is this address blocked, and on which channels</Card>
  <Card title="List addresses" icon="list" href="/api-reference/outbound-blocklist/list">Page through the whole list, newest first</Card>
</CardGroup>