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

# Suppression

> View and manage your email suppression list

# Suppression

Numonic maintains a suppression list for your account. Addresses are added automatically when a hard bounce or spam complaint is received from SES. Any future send to a suppressed address filters that recipient out before the email leaves your account — no bounce, no complaint, no wasted SES cost.

All suppression endpoints require **JWT authentication**.

***

## List suppressed addresses

```
GET /api/v1/suppression
```

Returns all suppressed addresses for your account with pagination.

### Request

```bash theme={null}
curl "https://api.numonic.com/api/v1/suppression?page=1&limit=50" \
  -H "Authorization: Bearer YOUR_JWT"
```

### Query parameters

| Parameter | Type    | Default | Description      |
| --------- | ------- | ------- | ---------------- |
| `page`    | integer | `1`     | Page number      |
| `limit`   | integer | `50`    | Results per page |

### Response `200`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id":            "550e8400-e29b-41d4-a716-446655440000",
      "email":         "bounced@example.com",
      "reason":        "hard_bounce",
      "suppressed_at": "2026-04-09T10:30:05.000Z"
    },
    {
      "id":            "550e8400-e29b-41d4-a716-446655440001",
      "email":         "complained@example.com",
      "reason":        "complaint",
      "suppressed_at": "2026-03-15T08:12:00.000Z"
    }
  ],
  "pagination": {
    "page":        1,
    "limit":       50,
    "total":       2,
    "total_pages": 1
  }
}
```

### Suppression entry fields

| Field           | Description                     |
| --------------- | ------------------------------- |
| `id`            | Unique ID for the entry         |
| `email`         | Suppressed address              |
| `reason`        | `hard_bounce` or `complaint`    |
| `suppressed_at` | When the address was suppressed |

***

## Remove a suppressed address

```
DELETE /api/v1/suppression/:email
```

Removes an address from the suppression list. Future sends to this address will no longer be filtered.

URL-encode the email address in the path (`@` → `%40`).

### Request

```bash theme={null}
curl -X DELETE "https://api.numonic.com/api/v1/suppression/bounced%40example.com" \
  -H "Authorization: Bearer YOUR_JWT"
```

### Response `200`

```json theme={null}
{
  "success": true,
  "message": "Suppression removed for bounced@example.com"
}
```

### Errors

| Status | Code           | Cause                                       |
| ------ | -------------- | ------------------------------------------- |
| `401`  | `UNAUTHORIZED` | Missing or invalid JWT                      |
| `404`  | `NOT_FOUND`    | No suppression entry found for this address |

***

## How automatic suppression works

Numonic ingests SES feedback events and applies suppression automatically:

* **Hard bounce** (`Permanent` bounce type) → address added to suppression list
* **Spam complaint** → address added to suppression list

This happens before any future send is attempted. When you submit a send, Numonic checks every recipient against your suppression list. Suppressed recipients are excluded from the send and returned in `suppressed_recipients` on the response. The send still goes out to any non-suppressed recipients.

<Warning>
  Only remove a suppression if you have a good reason to believe future sends will succeed — for example, a recipient fixed their inbox and explicitly asked to receive emails again. Repeatedly sending to suppressed addresses risks your SES sending reputation.
</Warning>