# Suppression

> Couryo's suppression list protects your reputation. Reasons, streams, and how to list, add and remove addresses through the API.

Source: https://couryo.com/en/docs/suppressions

The suppression list holds addresses Couryo will no longer send to. It protects your reputation: insisting on an address that does not exist, or on someone who complained, drags down delivery of all your email.

## Reasons

| `reason` | When it is added | Applies to |
|---|---|---|
| `hard_bounce` | the address does not exist (`5.1.x`) | all streams |
| `complaint` | the recipient marked the email as spam | all streams |
| `unsubscribe` | the recipient unsubscribed | only the stream they unsubscribed from (usually `marketing`) |
| `manual` | you added it | the stream you choose |

A marketing unsubscribe **never** blocks transactional email: someone who left the newsletter still gets the password reset.

## What happens when sending

If **some** recipients are suppressed, the email goes to the others and the timeline gets a `suppressed` event for each skipped address. If **every** recipient is suppressed, the send is refused with `422 recipient_suppressed`, and `param` points to the first one (`to[0]`). In a batch, only the affected item is refused.

Temporary bounces (`4.x.x`) also lead to suppression when the same address bounces on 3 different days.

## List

```bash title="cURL"
curl "https://api.couryo.com/v1/suppressions?limit=25" \
  -H "Authorization: Bearer $COURYO_API_KEY"
```

```json title="Response"
{
  "data": [
    { "email": "maria@company.com", "reason": "hard_bounce", "stream": "all", "created_at": "2026-10-07T18:31:04Z" }
  ],
  "has_more": false
}
```

## Add

```bash title="cURL"
curl https://api.couryo.com/v1/suppressions \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "do-not-send@example.com", "stream": "marketing" }'
```

## Remove

```bash title="cURL"
curl -X DELETE https://api.couryo.com/v1/suppressions/maria@company.com \
  -H "Authorization: Bearer $COURYO_API_KEY"
```

The address leaves every stream (`204`). Remove an address only when you are sure the problem is solved (for example, the person confirmed the address works again).

## Scopes and filters

- Listing needs the `read` scope; adding and removing, `admin`.
- The list accepts `q` (part of the address), `reason` and `limit` (default 100), with `starting_after` for the next page.
- Added addresses always get the `manual` reason; `stream` can be `transactional`, `marketing` or `all` (default). An address already on the list returns `409 already_suppressed`.