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

# Manage suppressions

> Understand and manage the suppression list

## What is the suppression list?

The suppression list is a set of email addresses that Torpedo will automatically block from receiving emails. Addresses are added when:

* **Hard bounce** — the address doesn't exist or the domain doesn't accept mail
* **Spam complaint** — the recipient marked your email as spam

Torpedo adds addresses automatically to protect your sender reputation. Sending to bounced or complaining addresses damages your deliverability scores.

***

## What happens when you send to a suppressed address

The send request returns `422 Unprocessable Entity`:

```json theme={null}
{
  "errors": [{ "message": "Recipient is suppressed" }]
}
```

The email is not queued and no credit is consumed.

***

## View suppressed addresses

```bash theme={null}
curl https://api.torpedo.co.mz/api/v1/suppressions \
  -H "X-API-Key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "data": [
    {
      "address": "user@example.com",
      "reason": "hard_bounce",
      "channel": "email",
      "suppressedAt": "2026-04-15T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "perPage": 20, "page": 1 }
}
```

***

## Remove a suppression

Only remove a suppression if you have a legitimate reason — e.g. the recipient confirms they want to receive emails and the bounce was a temporary issue.

```bash theme={null}
curl -X DELETE "https://api.torpedo.co.mz/api/v1/suppressions/user%40example.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

<Note>URL-encode the address — replace `@` with `%40`.</Note>

***

## Suppression vs unsubscribe

Suppressions are triggered automatically by delivery events (bounces, complaints).\
They are not the same as user-initiated unsubscribes — Torpedo does not manage marketing unsubscribe preferences. That is your application's responsibility.

***

## SMS suppressions

SMS numbers are suppressed automatically when a permanent delivery failure is detected. Torpedo does not expose carrier-specific error codes — the reason is always recorded as `"hard_bounce"`.

### What happens when you send to a suppressed number

The send request returns `422 Unprocessable Entity`:

```json theme={null}
{
  "errors": [{ "message": "Recipient '+258841234567' is suppressed (reason: hard_bounce)" }]
}
```

The message is not queued and no credit is consumed.

### View suppressed numbers

SMS suppressions appear in the same list as email suppressions. Filter by `channel`:

```bash theme={null}
curl "https://api.torpedo.co.mz/api/v1/suppressions?channel=sms" \
  -H "X-API-Key: YOUR_API_KEY"
```

The `channel` field in each entry will be `"sms"`.

### Remove an SMS suppression

```bash theme={null}
curl -X DELETE "https://api.torpedo.co.mz/api/v1/suppressions/%2B258841234567?channel=sms" \
  -H "X-API-Key: YOUR_API_KEY"
```

<Note>
  Phone numbers contain a `+` sign — URL-encode it as `%2B`. For example, `+258841234567` becomes
  `%2B258841234567`.
</Note>