Suppressions Management
Relevant source files
The following files were used as context for generating this wiki page:
Suppressions Management handles email addresses to which Resend prevents delivery. This system manages entries generated by bounces, complaints, or manual additions to maintain sender reputation and comply with recipient preferences.
The Resend .NET SDK provides methods to add, list, retrieve, and remove suppressions, supporting both single-address operations and batch processing.
Sources: src/Resend/Suppression.cs, src/Resend/IResend.cs:1229-1309
Data Models and Architecture
The suppression system uses three primary data structures to represent blocked recipients. Suppression represents a full record, while SuppressionSummary is a lightweight version used in paginated lists.
Class Relationships
The following diagram illustrates the properties and relationships of the suppression models.
The SuppressionSummary model excludes the Object discriminator found in the full Suppression response.
Sources: src/Resend/Suppression.cs:17-57, src/Resend/SuppressionSummary.cs:16-52
Model Field Descriptions
| Field | Type | Description |
|---|---|---|
Id | Guid | Unique identifier for the suppression record. |
Email | string | The email address blocked from delivery. |
Origin | SuppressionOrigin | The reason for suppression (Bounce, Complaint, or Manual). |
SourceId | string? | The ID of the event causing suppression. Null for manual origin. |
MomentCreated | DateTime | The UTC timestamp when the record was created. |
The SourceId is stored as a free-text string because the underlying data layer does not strictly enforce a UUID format.
Sources: src/Resend/Suppression.cs:17-57, src/Resend/SuppressionSummary.cs:42-45, tests/Resend.Tests/SuppressionTests.cs:44-53
Client Operations
The ResendClient implements the IResend interface to interact with the Resend API /suppressions endpoints.
Single Operations
You manage individual suppressions using methods that target specific email addresses or record identifiers.
- SuppressionAddAsync: Adds a single email address to the list. Returns a
Guidfor the new record. - SuppressionRetrieveAsync: Fetches a full suppression record using either the Record ID or the email address.
- SuppressionRemoveAsync: Deletes a suppression record to resume delivery to the address.
Sources: src/Resend/ResendClient.Suppressions.cs:10-20, src/Resend/ResendClient.Suppressions.cs:51-68, src/Resend/IResend.cs:1230-1270
Batch Operations
Batch methods allow processing up to 100 addresses in a single request.
The API server normalizes addresses by trimming whitespace and converting to lowercase before deduplicating. Consequently, the returned list of identifiers may be shorter than the input list of addresses.
Sources: src/Resend/ResendClient.Suppressions.cs:71-79, tools/Resend.ApiServer/Controllers/SuppressionController.cs:141-149, src/Resend/IResend.cs:1272-1282
API Endpoints and Parameters
The following table summarizes the endpoints used by the suppression module.
| Method | Endpoint | Description |
|---|---|---|
POST | /suppressions | Creates a single suppression record. |
GET | /suppressions | Lists suppressions with optional pagination and origin filters. |
GET | /suppressions/{idOrEmail} | Retrieves a specific record by ID or URL-encoded email. |
DELETE | /suppressions/{idOrEmail} | Removes a suppression by ID or email. |
POST | /suppressions/batch/add | Adds multiple addresses simultaneously. |
POST | /suppressions/batch/remove | Removes multiple suppressions by IDs or addresses. |
Sources: src/Resend/ResendClient.Suppressions.cs:10-101, tools/Resend.ApiServer/Controllers/SuppressionController.cs:17-113
Filtering and Pagination
The SuppressionListAsync method accepts a SuppressionListQuery object to filter results.
- Origin: Filters the list by
bounce,complaint, ormanual. - Limit: Sets the number of records per page.
- Before/After: Provides cursor-based pagination using suppression identifiers.
Sources: src/Resend/ResendClient.Suppressions.cs:24-48, tests/Resend.Tests/SuppressionRequestTests.cs:27-40
Validation and Normalization Logic
The system enforces strict validation and normalization rules to ensure data consistency.
- Validation: If a batch request contains a blank or whitespace-only email string, the API rejects the entire batch with a
422 Unprocessable Entitystatus. - Normalization: The server processes all addresses to be lowercase and distinct before storage.
- URL Encoding: When retrieving or removing by email address, the SDK escapes data to ensure symbols (like
+in sub-addressing) survive transport.
Sources: tools/Resend.ApiServer/Controllers/SuppressionController.cs:122-136, src/Resend/ResendClient.Suppressions.cs:57, tests/Resend.Tests/ResendClientTests.Suppressions.cs:134-143
Webhook Integration
External systems can monitor suppression changes through webhooks. The SuppressionEventData structure carries the suppression details during suppression.added and suppression.removed events.
Webhook payloads include the suppression Id, Email, Origin, and the SourceId of the event that triggered the block.
Sources: src/Resend.Webhooks/SuppressionEventData.cs:10-44, tests/Resend.Webhooks.Tests/WebhookEventConverterTests.cs:176-192
Summary
Suppressions Management provides a robust mechanism for controlling email deliverability. By combining single and batch operations with automated normalization and webhook notifications, the system ensures that bounced and complained addresses are reliably excluded from future campaigns while allowing for manual intervention when necessary.