Suppressions Management

Relevant source files

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

• src/suppressions/suppressions.ts
• src/suppressions/suppressions.spec.ts
• src/suppressions/batch/batch.spec.ts
• src/suppressions/interfaces/suppression-list-entry.ts
• src/suppressions/interfaces/list-suppressions.interface.ts
• src/request-options.spec.ts

Suppressions Management handles the exclusion of specific email addresses from receiving communications. The system records addresses that triggered bounces, registered complaints, or were manually suppressed to maintain sender reputation and comply with recipient preferences.

The module provides interfaces for individual suppression management and bulk operations through the Suppressions and Batch classes.

Architecture and Components

The Suppressions class acts as the primary entry point for suppression logic. It maintains a reference to a Batch instance for bulk processing.

This diagram shows the relationship between the main Resend client and the suppression components.
Sources: src/suppressions/suppressions.ts:33-37, src/request-options.spec.ts:160-167

Data Model

A suppression record contains the recipient's identity, the reason for suppression (origin), and metadata regarding its creation.

Suppression Object Fields

Field	Type	Description
id	string	Unique identifier for the suppression record.
email	string	The suppressed email address.
origin	string	The cause of suppression: bounce, complaint, or manual.
source_id	string | null	Optional ID referencing the source of the suppression.
created_at	string	Timestamp indicating when the suppression was recorded.

Sources: src/suppressions/interfaces/suppression-list-entry.ts:1-13

Individual Suppression Management

The system manages single suppression entries through standard CRUD-like operations targeting the /suppressions endpoint.

Adding a Suppression

To suppress an email address, you call the add method. The system sends a POST request to the API.
Sources: src/suppressions/suppressions.ts:39-46

Retrieving and Removing

When retrieving or removing a record, you can provide either the record id or the email address. The library automatically encodes the identifier for the URL path. If the identifier contains special characters like +, they are converted to percent-encoded values (e.g., %2B).

This sequence shows how identifiers are processed before reaching the API.
Sources: src/suppressions/suppressions.ts:60-70, src/suppressions/suppressions.spec.ts:88-95

Batch Operations

The Batch sub-module processes multiple suppressions in a single request to improve efficiency.

1. Batch Add: Accepts a list of email addresses. You can add up to 100 suppressions per request.
2. Batch Remove: Accepts a list of ids or emails to delete multiple suppression records simultaneously.

Endpoints for these operations use the /suppressions/batch/add and /suppressions/batch/remove paths.
Sources: src/suppressions/batch/batch.spec.ts:22-45, src/suppressions/batch/batch.spec.ts:77-85

List Filtering and Pagination

You can list suppression entries with optional filters and pagination parameters.

• Origin Filter: Filter results by bounce, complaint, or manual.
• Pagination: Use limit to control the number of results and before/after cursors for navigation.

The system builds the query string by combining the origin filter with standard pagination utilities.
Sources: src/suppressions/suppressions.ts:81-91, src/suppressions/interfaces/list-suppressions.interface.ts:11-13

Query Building Logic

This flow represents how the SDK transforms method options into a valid API request URL.
Sources: src/suppressions/suppressions.ts:81-91

Error Handling

The module validates required fields locally before making network requests. If you call get or remove with an empty string, the SDK returns a missing_required_field error without attempting a fetch.
Sources: src/suppressions/suppressions.ts:23-31, src/suppressions/suppressions.spec.ts:98-112

Summary

Suppressions Management provides a structured way to handle email delivery exclusions. By supporting both individual and batch operations, along with automated URL encoding and query building, it ensures that applications can efficiently maintain recipient suppression lists and sender health.