Email Suppressions
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/suppressions/Suppressions.java
- src/main/java/com/resend/services/suppressions/SuppressionsBatch.java
- src/main/java/com/resend/services/suppressions/model/Suppression.java
- src/main/java/com/resend/services/suppressions/model/SuppressionOrigin.java
- src/main/java/com/resend/services/suppressions/model/AddSuppressionsOptions.java
- src/main/java/com/resend/services/suppressions/model/RemoveSuppressionsOptions.java
- src/main/java/com/resend/services/suppressions/model/ListSuppressionsParams.java
Email Suppressions manage the list of email addresses that should not receive communications. This system prevents sending emails to addresses that have bounced, reported complaints, or been manually added to the blocklist. The module provides functionality to add, retrieve, list, and remove these restrictions through both single and batch operations.
Sources: Suppressions.java:11, SuppressionOrigin.java:8-14
Core Architecture
The Suppressions module is built on a service-oriented architecture where the Suppressions class acts as the primary entry point. It extends the BaseService to handle authentication and HTTP communication with the Resend API. The module separates concerns into single-resource management and batch operations handled by the SuppressionsBatch class.
Sources: Suppressions.java:11-31, SuppressionsBatch.java:11-30
Data Flow for Suppression Requests
The diagram below illustrates how the SDK processes a request to manage a suppression, from the client call to the API execution.
This diagram shows the relationship between single and batch operations. Sources: Suppressions.java:42-53, SuppressionsBatch.java:39-43
Suppression Properties and Origins
Each suppression entry contains metadata regarding why and when an email was suppressed. The origin field indicates the specific event that triggered the suppression.
Suppression Data Model
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the suppression record. |
email | String | The email address that is suppressed. |
origin | String | The reason for the suppression (bounce, complaint, manual). |
source_id | String | The ID of the email that triggered the suppression; null for manual. |
created_at | String | Timestamp of when the suppression was created. |
object | String | The type of object (always "suppression"). |
Sources: Suppression.java:8-25
Suppression Origins
The system categorizes suppressions into three distinct types:
- Bounce: The system automatically adds an email address after a delivery attempt results in a bounce.
- Complaint: The system adds an email address when a recipient marks an email as spam or files a complaint.
- Manual: A member of your team explicitly adds the email address to the suppression list.
Sources: SuppressionOrigin.java:8-15
Suppression Operations
Single Resource Management
You can manage individual suppressions using the Suppressions class methods.
- Add: Adds a single email to the suppression list.
- Remove: Deletes a suppression by providing either the unique suppression ID or the suppressed email address.
- Get: Retrieves details for a specific suppression using its ID or email address.
Sources: Suppressions.java:42-78
Batch Operations
The SuppressionsBatch class handles bulk updates to the suppression list.
- Add Batch: You can add up to 100 email addresses in a single request. The
AddSuppressionsOptionsvalidator ensures the list contains between 1 and 100 entries. - Remove Batch: You can remove up to 100 suppressions at once. You must provide either a list of emails or a list of IDs, but providing both is prohibited.
Sources: SuppressionsBatch.java:39-55, AddSuppressionsOptions.java:78-86, RemoveSuppressionsOptions.java:108-112
Listing and Filtering
The list method retrieves suppression records with support for pagination and filtering.
This flowchart shows the logic for retrieving suppression lists. Sources: Suppressions.java:86-104, ListSuppressionsParams.java:65-78
The ListSuppressionsParams class allows filtering by SuppressionOrigin and controlling the result set size via a limit.
Sources: ListSuppressionsParams.java:43-60
Validation Logic
The module implements client-side validation for batch operations to ensure API compatibility.
- Add Batch Constraints: The builder throws an
IllegalArgumentExceptionif the emails list is empty or exceeds 100 addresses. - Remove Batch Constraints: The builder requires exactly one of
emailsoridsto be populated. If both are null/empty or both are provided, it throws anIllegalArgumentException.
Sources: AddSuppressionsOptions.java:80-85, RemoveSuppressionsOptions.java:108-111
Conclusion
The Email Suppressions module provides a structured way to maintain sender reputation by managing email blocklists. By automating suppressions for bounces and complaints while allowing manual overrides and batch processing, it ensures compliant and effective email delivery workflows.