# List email suppressions

Lists deployment-global suppressions for system callers. With accountId, lists that account's complaints; account callers may select only their own account.

## `GET /api/v1/suppressions`

### Query parameters

- `limit` (integer, ≥ 1, ≤ 200) — Page size (default 100)
- `cursor` (string) — Opaque page cursor from a previous response
- `accountId` (string, 1–128 chars) — Sending account whose complaint suppressions to inspect or modify

### Responses

**200** — List of suppressed email addresses

`application/json` → SuppressionList

- `suppressions` (Suppression[], required)
  - `address` (string, required) — Normalized (lowercased) recipient email address
  - `detail` (string | null, required) — Diagnostic error message or feedback detail from the bounce or complaint report
  - `eventCount` (integer <int64>, required) — Total number of bounce or complaint events recorded for this address
  - `firstEventAt` (integer <int64>, required) — Timestamp of first suppression event in epoch seconds
  - `lastEventAt` (integer <int64>, required) — Timestamp of most recent suppression event in epoch seconds
  - `reason` ("complaint" | "hard_bounce", required) — Reason for suppression ('complaint' from FBL report, or 'hard_bounce' from MTA)
  - `sourceDeliveryId` (string | null, required) — Delivery ID that triggered this suppression, or null
  - `accountId` (string) — Sending account whose complaint blocks this recipient; absent for a deployment-global block
- `nextCursor` (string) — Opaque cursor for the next page; absent on the last page

**400** — validation_failed

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**403** — insufficient_scope — mailbox credentials or a foreign account; system_credentials_required — the global listing requires system credentials

`application/json` → ErrorBody

**503** — suppression_moving: the address's bucket is being moved; retry after the Retry-After delay. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/suppressions' \
  -H 'Authorization: Bearer oek_…'
```
