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

# Unsubscribes and compliance

> The suppression ledger and opt-out handling.

Anyreach keeps an org-scoped suppression ledger of addresses that should never be messaged again. Every recipient is considered subscribed unless their address is listed. Each send is checked against the ledger first, so an opt-out takes effect immediately.

## How the ledger works

The ledger is a single table of suppressed addresses, scoped to your organization. A row records the `address`, the `channel`, the `reason` it was added, and the date it was created. An address is unique per organization and channel, so the same address can be suppressed independently on different channels.

Before drafting or sending a reply, Anyreach checks whether the sender's address is suppressed. If it is, the message is still recorded as part of the conversation, but no reply is sent. The check runs again as a safety net right before the send, in case the address was suppressed between the inbound message and the outbound reply.

```
inbound message
   │
   ├─ control keyword? ── STOP  → add to ledger
   │                      START → remove from ledger
   │
   ├─ record the turn (always)
   │
   └─ suppressed?  ── yes → record only, no reply
                      no  → draft → re-check ledger → send
```

## What adds and removes addresses

Addresses land in the ledger automatically. You do not need to manage it by hand for normal opt-outs.

| Trigger                          | Effect          | Reason         |
| -------------------------------- | --------------- | -------------- |
| Inbound `STOP` keyword           | Address added   | `stop_keyword` |
| Hard bounce delivery event       | Address added   | `bounce`       |
| Spam complaint delivery event    | Address added   | `complaint`    |
| Inbound `START` keyword          | Address removed | —              |
| **Resubscribe** in the dashboard | Address removed | —              |

### Control keywords

Anyreach scans the body of each inbound message for a control keyword. A `STOP` keyword adds the sender to the ledger; a `START` keyword removes them. Either way the message is still recorded as a conversation turn, it just does not get a reply.

The keywords are matched case-insensitively against the message:

| Keyword | Recognized words                                                               |
| ------- | ------------------------------------------------------------------------------ |
| `STOP`  | `stop`, `stopall`, `unsubscribe`, `cancel`, `end`, `quit`, `optout`, `opt-out` |
| `START` | `start`, `unstop`, `subscribe`, `resume`, `yes`                                |
| `HELP`  | `help`, `info`                                                                 |

<Note>
  A `HELP` keyword does not change the ledger. It is recognized so the message is not treated as normal content to reply to.
</Note>

### Bounces and complaints

Delivery events feed the ledger too. When a send hard-bounces, the recipient is added with reason `bounce`. When a recipient marks a message as spam, they are added with reason `complaint`. See [delivery status](/email/delivery-status) for how these events are reported.

## The unsubscribe footer

By default, replies append a footer so recipients always have a way to opt out:

```
Reply STOP to unsubscribe.
```

The footer is added to both the HTML and plain-text parts of the email. It is controlled per email agent by the `include_unsubscribe_footer` property, which is on by default. Configure it on the agent — see [configuring an email agent](/email/configuring-an-email-agent).

## The Unsubscribes page

Open **Settings → Unsubscribes** to see the ledger. The page lists every suppressed address with its channel, reason, and date, newest first.

| Column      | Description                                                          |
| ----------- | -------------------------------------------------------------------- |
| **Address** | The suppressed address                                               |
| **Channel** | The channel the suppression applies to                               |
| **Reason**  | Why it was added (for example `stop_keyword`, `bounce`, `complaint`) |
| **Date**    | When it was added                                                    |

To opt an address back in, select **Resubscribe** on its row. This removes the row from the ledger, and the address becomes eligible for messaging again on that channel.

<Warning>
  Only resubscribe an address when you have a clear basis to do so. Bounce and complaint suppressions exist to protect your sending reputation; re-messaging a complaining recipient can harm deliverability.
</Warning>

## API

The ledger is exposed under the `/core` prefix. Both endpoints are organization-scoped via your credentials.

| Method   | Path                      | Scope                                        |
| -------- | ------------------------- | -------------------------------------------- |
| `GET`    | `/core/unsubscribes`      | `unsubscribes:read` or `unsubscribes:manage` |
| `DELETE` | `/core/unsubscribes/{id}` | `unsubscribes:manage`                        |

`GET /core/unsubscribes` returns the suppression rows ordered by `created_at` descending. `DELETE /core/unsubscribes/{id}` resubscribes an address by removing its row.

```bash theme={null}
# List suppressions
curl https://api.anyreach.ai/core/unsubscribes \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"

# Resubscribe (remove a row)
curl -X DELETE https://api.anyreach.ai/core/unsubscribes/<id> \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"
```

<Note>
  `X-Anyreach-Org` is required for user PATs (`pat_`). Organization API keys (`ak_`) carry their organization implicitly.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Configuring an email agent" icon="gear" href="/email/configuring-an-email-agent">
    Set the unsubscribe footer and other reply properties.
  </Card>

  <Card title="Delivery status" icon="envelope" href="/email/delivery-status">
    How bounces and complaints are reported.
  </Card>
</CardGroup>