# GET /v1/suppressions

List the suppressed addresses

Addresses a stream of the server will not send to: hard bounces, spam complaints and entries added by hand, newest first, one page at a time. The default stream unless streamId names another; every stream has a list of its own. A send to any of them is refused with recipient_suppressed.

Takes a server key (`sk_…`, or `sk_test_…` on a test server) as a bearer token. TypeScript: `sendora.suppressions.list(query)`. Python: `sendora.suppressions.list(stream_id=..., limit=..., after=...)`.

## Parameters

- `streamId` (query, string (uuid)): The stream whose list is meant; the default transactional stream when absent.
- `limit` (query, integer (1 to 1000)): Page size, 1 to 1000.
- `after` (query, string (uuid)): The `next` value of the previous page.

## Responses

### 200 A page of the stream's suppression list, newest first.

- `suppressions` (array of object, required)
  - `streamId` (string (uuid), required): The stream whose list the address is on.
  - `address` (string, required): The recipient, lower-cased.
  - `reason` ("hard_bounce" | "spam_complaint" | "manual" | "unsubscribe", required): A hard bounce or a manual entry may be lifted here; a spam complaint or the recipient’s own unsubscribe only by Sendora support. manual is an address added by hand in the dashboard.
  - `messageId` (string (uuid) or null, required): The message whose bounce or complaint put it here.
  - `createdAt` (string (date-time), required)
- `next` (string (uuid) or null, required): Pass as `after` for the next page; null on the last.

Example:

```json
{
  "suppressions": [
    {
      "streamId": "3d1a2b4c-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "address": "anna@example.com",
      "reason": "hard_bounce",
      "messageId": "5f432ffd-c005-499b-aa3a-5b8a088ea20e",
      "createdAt": "2026-09-15T12:00:00.000Z"
    }
  ],
  "next": null
}
```

## Errors

Every error answers `error`, the code, and `message`, a sentence for a person. A code that adds fields is shown in full below the table.

| Code | Status | Meaning |
| --- | --- | --- |
| `invalid_request` | 400 | The body, the query or a header does not match what the route takes. |
| `unauthorized` | 401 | The key is missing, malformed or revoked. |
| `wrong_token_kind` | 403 | The key is of the other kind: a server key (sk_) where an account key (ak_) is needed, or the reverse. The message names the kind the operation takes. |
| `stream_not_found` | 422 | The streamId names no stream of this server. |
| `stream_not_sendable` | 422 | An inbound stream receives mail; it takes no messages and has no suppression list. Name a transactional or broadcast stream. |

### `invalid_request`

- `issues` (array of object): One entry per invalid field; absent when a header is wrong.
  - `path` (string, required): The field, dotted, such as to.0.email; empty when the whole body is wrong.
  - `message` (string, required)

Example:

```json
{
  "error": "invalid_request",
  "message": "The request is invalid: to.0: Invalid email address",
  "issues": [
    {
      "path": "to.0",
      "message": "Invalid email address"
    }
  ]
}
```