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

# Suppression list

> Addresses no agent of your organization may reach.

Every email, text, call and LinkedIn message an agent of your organization sends is checked against one list first. A listed address is not reached on that channel, by a direct call or by a goal.

## Refusals

A send refused before it reaches anyone is not charged:

| Status | `error` | Why | Retry |
| - | - | - | - |
| 403 | `recipient_suppressed` | The address is on this list for the channel | Never on this channel |
| 429 | `quiet_hours` | A text or call would arrive between 21:00 and 08:00 the recipient's time | At `retry_at` |
| 429 | `daily_cap_reached` | The agent or goal sent its [daily allowance](https://docs.oneshotagent.com/api-reference/approvals/set-action-policy.md#outbound-limits) on this channel | At `retry_at` |
| 403 | `recipient_timezone_required` | Nothing places the recipient closely enough to find a waking hour | With `recipient_timezone` |

The recipient's time zone comes from `recipient_timezone` on the send, then the goal case's `timezone`, then its `country` when the country keeps one clock, and last the number, from libphonenumber's data.

A number in several possible zones waits for an hour that is daytime in all of them. The 429s also set `Retry-After`. Inside a goal, the agent is told the reason and `retry_at`, and a case waits until then.

## How addresses get on it

| Source | Channel | `reason` |
| - | - | - |
| A text reply of `STOP`, `STOPALL`, `UNSUBSCRIBE`, `CANCEL`, `END`, `QUIT`, `OPTOUT` or `REVOKE` | `sms` | `opt_out` |
| The carrier reports that the number opted out | `sms` | `opt_out` |
| An email bounces | `email` | `bounce` |
| A recipient marks an email as spam | `email` | `opt_out` |
| An admin adds one, or uploads a list | any | `do_not_contact` or `manual` |

A reply of `START`, `UNSTOP` or `YES` lifts an opt-out that a `STOP` reply made. It never lifts an entry an admin added.

Addresses are stored in one form: emails in lower case, phone numbers in international format (`+14155550123`), LinkedIn profiles by their handle. An entry on channel `any` blocks every channel.

## API

Admins only. Each change is an audit entry under Policies (`org.suppression_added`, `org.suppression_uploaded`, `org.suppression_removed`).

| Route | Does |
| - | - |
| `GET /v1/org/suppressions?channel=&q=&limit=&cursor=` | Newest first, up to 200 a page; `next_cursor` continues |
| `POST /v1/org/suppressions` `{ channel, address, reason? }` | Adds one; `reason` is `do_not_contact` (default) or `manual` |
| `POST /v1/org/suppressions/upload` `{ csv, channel? }` | Adds up to 20,000; returns `added`, `already_listed` and `invalid` |
| `DELETE /v1/org/suppressions/:id` | Removes one |

The upload is the file's text: one address per line, or `address,channel`. A header line is skipped. `channel` (default `any`) applies to lines without one.

```json theme={null}
{ "csv": "address,channel\njane@example.com,email\n+14155550123,sms\nhttps://www.linkedin.com/in/jane-doe/,linkedin", "channel": "any" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.