---
title: "Suppressions API"
description: "Suppressions in the OneSend API: 6 endpoints. One suppression list shared by every provider."
url: https://onesend.email/docs/api-reference/suppressions/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Suppressions

One suppression list shared by every provider.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## List suppressed addresses (shared across every provider)

GET `/v1/suppressions`

One list for every provider: an address that bounced or complained anywhere (provider webhooks, status polls, imported provider lists, send-time rejections) is never sent to again through any provider. Each entry says where it came from and, for temporary entries, when it ends.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `q` | query | `string` |  |
| `reason` | query | `string` |  |
| `limit` | query | `integer` | Default 100. 1 to 500. |
| `cursor` | query | `string` |  |
| `origin` | query | `"webhook" \| "webhook_unmatched" \| "poll" \| "sync" \| "send" \| "manual" \| "import" \| "escalation" \| "unsubscribe" \| "api" \| …` | Where entries came from (`legacy`: added before origins were recorded). |
| `connectionId` | query | `string` | Entries that came from this sending provider connection. |
| `provider` | query | `string` |  |
| `scope` | query | `"all" \| "broadcast"` |  |
| `temporary` | query | `"true" \| "false"` | `true`: only entries that end (repeated soft bounces, provider blocks); `false`: only permanent ones. |
| `expired` | query | `"true" \| "false"` | Include temporary entries that already ended (removed by housekeeping within the hour). Default false. |

### Responses

`200` Success

```
{
  "data": [{
    "email": string,
    "reason": "hard_bounce" | "complaint" | "unsubscribe" | "manual" | "blocked" | "soft_bounce_repeated",
    "scope": "all" | "broadcast",
    "source": string or null,
    "createdAt": string,
    "origin": "webhook" | "webhook_unmatched" | "poll" | "sync" | "send" | "manual" | "import" | "escalation" | "unsubscribe" | "api" | …,
    "provider": string or null,
    "connectionId": string or null,
    "detail": string or null,
    "expiresAt": string or null,
    "updatedAt": string or null,
    "allProviders": true
  }],
  "nextCursor": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Suppress an address

POST `/v1/suppressions`

An existing hard bounce or complaint is never downgraded; the wider scope wins; a permanent entry replaces a temporary one.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email`required | `string (email)` |  |
| `reason` | `"hard_bounce" \| "complaint" \| "unsubscribe" \| "manual"` | Default "manual". |
| `scope` | `"all" \| "broadcast"` | Default "all". |

### Responses

`201` Success

```
{
  "email": string,
  "reason": "hard_bounce" | "complaint" | "unsubscribe" | "manual" | "blocked" | "soft_bounce_repeated",
  "scope": "all" | "broadcast",
  "source": string or null,
  "createdAt": string,
  "origin": "webhook" | "webhook_unmatched" | "poll" | "sync" | "send" | "manual" | "import" | "escalation" | "unsubscribe" | "api" | …,
  "provider": string or null,
  "connectionId": string or null,
  "detail": string or null,
  "expiresAt": string or null,
  "updatedAt": string or null,
  "allProviders": true
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Suppression counts by reason, origin and provider connection

GET `/v1/suppressions/stats`

Entries in force (temporary entries that ended are not counted).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "total": number,
  "byReason": map of number,
  "byOrigin": map of number,
  "byConnection": map of number
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Provider suppression sync status per connection

GET `/v1/suppressions/sync`

For each connected provider: whether its own suppression list can be imported, the last run and its result, and the next run. Lists are imported when a provider is connected and then every few hours (`providerSync.intervalHours`, default 6).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "connectionId": string,
    "provider": string,
    "name": string,
    "kind": "suppressions" | "suppressions_push" | "status",
    "supported": boolean,
    "status": "idle" | "running" | "error" | "unsupported",
    "inProgress": boolean,
    "lastRunAt": string or null,
    "lastSuccessAt": string or null,
    "nextRunAt": string or null,
    "lastResult": {
      "ok": boolean,
      "at": string,
      "imported": number,
      "updated": number,
      "seen": number,
      "pushed": number,
      "polled": number,
      "events": number,
      "pages": number,
      "done": boolean,
      "error": string or null,
      "unsupported": boolean
    },
    "total": number
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Import provider suppression lists now

POST `/v1/suppressions/sync`

Starts an import of the providers' own suppression lists in the background (`GET /v1/suppressions/sync` shows progress).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `connectionId` | `string` | One connection; default: every connection that supports it. |

### Responses

`202` Success

```
{
  "data": [{
    "connectionId": string,
    "provider": string,
    "name": string,
    "kind": "suppressions" | "suppressions_push" | "status",
    "supported": boolean,
    "status": "idle" | "running" | "error" | "unsupported",
    "inProgress": boolean,
    "lastRunAt": string or null,
    "lastSuccessAt": string or null,
    "nextRunAt": string or null,
    "lastResult": {
      "ok": boolean,
      "at": string,
      "imported": number,
      "updated": number,
      "seen": number,
      "pushed": number,
      "polled": number,
      "events": number,
      "pages": number,
      "done": boolean,
      "error": string or null,
      "unsupported": boolean
    },
    "total": number
  }]
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Remove an address from the suppression list

DELETE `/v1/suppressions/{email}`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `email`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
