Suppressions Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/suppressions/index.ts
• src/commands/suppressions/list.ts
• src/commands/suppressions/utils.ts
• src/commands/suppressions/batch/remove.ts
• skills/resend-cli/references/suppressions.md
• tests/commands/suppressions/add.test.ts
• tests/commands/suppressions/get.test.ts
• tests/commands/suppressions/delete.test.ts

Suppressions Management allows you to control the list of email addresses that Resend blocks from receiving future emails. This system prevents sending to addresses that have hard bounced, reported spam, or been manually added by an administrator.

The feature is currently in a beta phase and requires account-level enrollment. Commands are visible in the CLI but return API errors if the feature is not enabled for the specific Resend account.

Sources: src/commands/suppressions/index.ts:13-15, skills/resend-cli/references/suppressions.md:5-7

Core Data Model

A suppression entry identifies a blocked recipient and the reason for the block.

Field	Type	Description
id	string	Unique identifier for the suppression (prefixed with sup-)
email	string	The suppressed email address
origin	string	The source of the suppression: bounce, complaint, or manual
source_id	string | null	ID of the event that triggered the suppression (e.g., a bounce event)
created_at	string	ISO 8601 timestamp of when the entry was created

Sources: src/commands/suppressions/utils.ts:4-10, skills/resend-cli/references/suppressions.md:9-13

Suppression Origins

The origin field defines how an address entered the suppression list:

• bounce: Added automatically by the system after a hard bounce.
• complaint: Added automatically by the system after a spam complaint.
• manual: Added by a user via the CLI or API.

Sources: src/commands/suppressions/index.ts:18-20, skills/resend-cli/references/suppressions.md:9-13

Command Architecture

The suppressions command group is organized into subcommands for single-resource actions and batch operations.

The diagram shows the hierarchy of the suppressions command and its subcommands.
Sources: src/commands/suppressions/index.ts:28-32, skills/resend-cli/references/suppressions.md

Retrieval and Filtering

The list command retrieves suppression entries with support for pagination and origin-based filtering.

This sequence shows the flow of a filtered list request from the user to the Resend API.
Sources: src/commands/suppressions/list.ts:50-62, tests/commands/suppressions/list.test.ts:108-115

Pagination

The list command utilizes cursor-based pagination via --after and --before flags. By default, the CLI fetches 10 items per page, but this is configurable between 1 and 100 using the --limit flag.

Sources: src/commands/suppressions/list.ts:13-25, skills/resend-cli/references/suppressions.md:21-25

Resource Management Actions

The CLI provides methods to create, retrieve, and remove suppressions.

Adding Suppressions

Users can manually suppress an email address using the add command. This creates an entry with the manual origin. In non-interactive environments, the <email> argument is required.

Sources: tests/commands/suppressions/add.test.ts:57-61, skills/resend-cli/references/suppressions.md:33-37

Getting and Deleting

Both get and delete commands are flexible; they accept either the internal suppression ID (e.g., sup-123) or the email address itself as a positional argument.

• Delete Confirmation: In non-interactive mode, the --yes flag is mandatory to bypass the confirmation prompt. Removing a suppression allows Resend to send to that address again.

Sources: tests/commands/suppressions/get.test.ts:55-68, tests/commands/suppressions/delete.test.ts:74-85, skills/resend-cli/references/suppressions.md:15, skills/resend-cli/references/suppressions.md:47-53

Batch Operations

Batch commands allow managing up to 100 entries in a single API request. These commands require a JSON file input containing an array of strings.

Batch Processing Flow

The flowchart describes the logic for processing batch files, including validation for the 100-entry API limit.
Sources: src/commands/suppressions/batch/remove.ts:58-90, skills/resend-cli/references/suppressions.md:65-68

Batch Configuration

Command	Required Flags	Optional Flags	Behavior
batch add	--file <path>	N/A	Suppresses all emails in the file.
batch remove	--file <path>	--ids	Removes suppressions by email (default) or by ID (with --ids).

Sources: src/commands/suppressions/batch/remove.ts:14-22, skills/resend-cli/references/suppressions.md:65-81

User Interface and Output

The CLI provides two primary output formats:

1. Interactive (TTY): Renders a human-readable table containing Email, ID, Origin, and Creation date.
2. Non-Interactive: Outputs raw JSON. This is triggered automatically in non-TTY environments (like CI/CD) or by the --json flag.

// Example of table rendering logic
export function renderSuppressionsTable(entries: Array<SuppressionEntry>): string {
  const rows = entries.map((s) => [s.email, s.id, s.origin, s.created_at]);
  return renderTable(
    ['Email', 'ID', 'Origin', 'Created'],
    rows,
    '(no suppressions)',
  );
}

Sources: src/commands/suppressions/utils.ts:19-27, tests/commands/suppressions/list.test.ts:94-101

Summary

Suppressions Management provides a robust interface for maintaining email deliverability by managing blocked recipients. By supporting both automated (bounce/complaint) and manual entries, alongside bulk processing capabilities, the system ensures senders can comply with spam regulations and maintain a healthy sender reputation.