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

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# ahasend suppressions: Manage Suppressions

> List, check, add, and remove suppressed email addresses in AhaSend from the command line, including domain-specific suppressions with expiry and bulk wipe.

AhaSend CLI `suppressions` commands let you inspect and manage blocked recipient addresses; this page explains their options.

Before running the examples, [log in](https://ahasend.com/docs/cli/authentication.md) with an API key that has the `suppressions:read`, `suppressions:write`, `suppressions:delete` and `suppressions:wipe` [scopes](https://ahasend.com/docs/api-reference/scopes.md#suppressions), and replace `example.com` in the `--domain` values with a test domain in your account.

## Overview

```text theme={null}
ahasend suppressions [subcommand] [flags]
```

Available subcommands:

* `list` - List suppressed email addresses
* `create` - Create a suppression for an email address
* `check` - Check if an email address is suppressed
* `delete` - Delete the suppressions of an email address
* `wipe` - Delete all suppressions from your account, or from one domain

Suppressions are email addresses that should not receive emails from your account. Each suppression applies to one domain: an address can have one suppression per domain, and no suppression covers every domain. Bounces and spam complaints add suppressions automatically, and unsubscribes come from the recipients themselves.

Unsubscribes and spam complaints are protected suppressions. `suppressions wipe` keeps them. `suppressions delete` deletes them like any other suppression. Table, plain and CSV output show whether each suppression is protected.

The commands check each email address and each `--domain` value before they send a request. An invalid value fails with exit code 4. An empty `--domain` fails too; leave the flag out instead.

## List Suppressions

List suppressed email addresses, with cursor pagination. Filter by email address, domain and creation time.

```bash theme={null}
# List suppressions
ahasend suppressions list

# Search for one email address
ahasend suppressions list --email user@example.com

# Filter by domain
ahasend suppressions list --domain example.com

# Suppressions created in the last 7 days
ahasend suppressions list --from-time 7d

# Fetch 100 suppressions, then the page after them
ahasend suppressions list --limit 100
ahasend suppressions list --limit 100 --after YOUR_CURSOR

# Print the API response as JSON
ahasend suppressions list --output json
```

`--from-time` and `--to-time` take an RFC 3339 time, such as `2026-09-01T00:00:00Z`, or a relative time that counts back from now, such as `24h` or `7d`. Pages work as [Lists and Pagination](https://ahasend.com/docs/cli/configuration.md#lists-and-pagination) describes; replace `YOUR_CURSOR` with the cursor of the previous page.

## Create Suppression

`--expires` is required. It takes a time after now: a relative time, such as `24h`, `30d`, `1w`, `3mo` or `1y`, or an RFC 3339 time in the future, such as `2027-12-31T23:59:59Z`. A time in the past fails before any request is sent.

Without `--domain`, the API creates a suppression for each domain the account has at that moment. Domains you add later are not covered.

```bash theme={null}
# Suppress an address on every current domain for 30 days
ahasend suppressions create user@example.com --reason "User requested unsubscribe" --expires 30d

# Suppress an address for one domain for 1 year
ahasend suppressions create user@example.com --domain example.com --reason "Email bounced" --expires 1y

# Suppress an address until a fixed time
ahasend suppressions create user@example.com --reason "Holiday pause" --expires 2027-12-31T23:59:59Z
```

`--reason` holds up to 255 characters. Give your own `--idempotency-key` when a script may retry the command; without it, each run generates a new key.

## Check Suppression

Without `--domain`, the command shows the address's suppressions on every domain, up to the API's default page of 100. With `--domain`, it shows only the suppression for that domain. It exits with code 0 whether or not the address is suppressed. `--output json` prints the API's list of matching suppressions.

```bash theme={null}
# Check the suppressions of an address on every domain
ahasend suppressions check user@example.com

# Check the suppression for one domain
ahasend suppressions check user@example.com --domain example.com
```

## Delete Suppression

With `--domain`, the command deletes only the suppression for that domain. Without it, the command deletes the address's suppressions on every domain, unsubscribes and complaints included.

The command asks for confirmation first, as [Prompts](https://ahasend.com/docs/cli/configuration.md#prompts) describes; `--force` (`-f`) skips it.

```bash theme={null}
# Suppress a test address on every current domain
ahasend suppressions create docs-delete-test@example.com --reason "Docs deletion test" --expires 1d

# Delete its suppression for one domain, with the confirmation prompt
ahasend suppressions delete docs-delete-test@example.com --domain example.com

# Delete its other suppressions, on every domain, without the prompt
ahasend suppressions delete docs-delete-test@example.com --force
```

The last step fails with exit code 5 when the address has no suppression left, as in an account with one domain: the API answers 404 when nothing matches.

## Wipe Suppressions

`suppressions wipe` deletes every suppression of the account, or of one domain with `--domain`. Protected suppressions (unsubscribes and spam complaints) are kept. The command prints a warning and asks for confirmation unless you give `--force` (`-f`).

Back up first. One list call saves one page of up to 100 suppressions. Repeat it with `--after` set to the page's `pagination.next_cursor`, in place of `YOUR_CURSOR`, until a page has no `next_cursor`. Add `--domain` to back up one domain.

The example below wipes one domain. Replace `example.com` with a test domain in your account: the wipe deletes every suppression of that domain that is not protected.

```bash theme={null}
# Suppress a test address for the test domain
ahasend suppressions create docs-wipe-test@example.com --domain example.com --reason "Docs wipe test" --expires 1d

# Back up the suppressions of that domain, one page at a time
ahasend suppressions list --domain example.com --limit 100 --output json > backup-1.json
ahasend suppressions list --domain example.com --limit 100 --after YOUR_CURSOR --output json > backup-2.json

# Wipe the suppressions of that domain, with the confirmation prompt
ahasend suppressions wipe --domain example.com

# Or wipe them without the prompt, as a script must
ahasend suppressions wipe --domain example.com --force
```

> [!WARNING]
>
> A wipe cannot be undone. Afterwards, email can be sent to every wiped address again, which can hurt your sender reputation. The backup is for your records only: the CLI cannot import it, and `suppressions create` adds one address at a time.

## Command Flags

These flags come from the CLI's `--help`. All commands also accept the [global flags](https://ahasend.com/docs/cli/configuration.md#global-flags).

### `suppressions check`

| Flag | Description and default |
| - | - |
| `--domain string` | Check suppression for specific domain only |

### `suppressions create`

| Flag | Description and default |
| - | - |
| `--domain string` | Suppress the address for this domain only (default: every current domain) |
| `--expires string` | Expiration time (e.g., `30d`, `2027-12-31T23:59:59Z`) (required) |
| `--idempotency-key string` | Idempotency key for safe retries (generated when omitted) |
| `--reason string` | Suppression reason (up to 255 characters) |

### `suppressions delete`

| Flag | Description and default |
| - | - |
| `--domain string` | Delete only the suppression for this domain (default: every domain) |
| `-f`, `--force` | Skip confirmation prompt |

### `suppressions list`

| Flag | Description and default |
| - | - |
| `--after string` | Return the page after this cursor |
| `--before string` | Return the page before this cursor |
| `--domain string` | Filter by specific domain |
| `--email string` | Filter by email address |
| `--from-time string` | Filter suppressions created after this time (RFC3339 or relative like '24h', '7d') |
| `--limit int32` | Maximum number of items to return (0-100; 0 uses the API default) |
| `--to-time string` | Filter suppressions created before this time (RFC3339 or relative) |

### `suppressions wipe`

| Flag | Description and default |
| - | - |
| `--domain string` | Domain to wipe suppressions for |
| `-f`, `--force` | Skip confirmation prompt |

## Next Steps

* [Send messages](https://ahasend.com/docs/cli/commands/messages.md)
* [View statistics](https://ahasend.com/docs/cli/commands/stats.md)

## Related Guides

* [Install the CLI](https://ahasend.com/docs/cli/installation.md), [CLI authentication](https://ahasend.com/docs/cli/authentication.md), [Suppression list API](https://ahasend.com/docs/api-reference/suppressions/get-suppressions.md).
* [Suppression durations](https://ahasend.com/docs/bounces.md#suppression-duration), [CLI configuration and output](https://ahasend.com/docs/cli/configuration.md), [API authentication](https://ahasend.com/docs/api-reference/authentication.md).
* [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md), [Domain setup](https://ahasend.com/docs/domains.md), [Sandbox behavior](https://ahasend.com/docs/send-api/sandbox.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.