Suppressions

Relevant source files

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

• src/Service/Suppression.php
• src/Suppression.php
• src/Service/Suppressions/Batch.php
• tests/Service/Suppression.php
• tests/Fixtures/Suppression.php

Suppressions manage email addresses that are excluded from receiving communications. The system identifies these addresses through automated triggers, such as bounces, or through manual administrative actions.

The Suppressions module provides tools to add, retrieve, list, and remove addresses from the suppression list. It supports both individual entry management and high-volume batch operations.

Data Model

The Resend\Suppression resource represents a single suppressed email entry. It contains metadata regarding the reason and timing of the suppression.

Field	Type	Description
id	string	The unique identifier for the suppression entry.
object	string	The type of object, typically "suppression".
email	string	The email address that is suppressed.
origin	string	The cause of suppression (e.g., "bounce", "manual", "complaint").
source_id	string|null	The ID of the email that triggered the suppression. Null for manual entries.
created_at	string	The timestamp when the suppression was recorded.

Sources: src/Suppression.php:5-13, tests/Fixtures/Suppression.php:5-12

Architecture and Service Structure

The Resend\Service\Suppression class acts as the primary interface for suppression operations. It extends the base Service class and utilizes a Transporter to communicate with the Resend API. It also instantiates a nested Batch service to handle multi-resource operations.

The diagram shows the relationship between the base service, the suppression service, and the batch sub-service.
Sources: src/Service/Suppression.php:9-19, src/Service/Suppressions/Batch.php:10-12

Suppression Operations

Individual Management

You can manage single suppressions using either the unique suppression ID or the specific email address.

1. Retrieve: The get() method fetches a single suppression record.
2. Add: The add() method accepts an array containing the email key to suppress a new address.
3. Remove: The remove() method deletes a suppression, allowing the address to receive emails again.

Sources: src/Service/Suppression.php:24-81, tests/Service/Suppression.php:10-28

Listing and Filtering

The list() method returns a Collection of suppression objects. You can filter the results by passing an options array.

Parameter	Type	Description
origin	string	Filter entries by their source (e.g., "manual").
limit	int	Limit the number of results returned.
before	string	Pagination cursor for records before a specific point.
after	string	Pagination cursor for records after a specific point.

Sources: src/Service/Suppression.php:58-60, tests/Service/Suppression.php:45-50

Batch Operations

The Resend\Service\Suppressions\Batch service handles operations involving up to 100 email addresses in a single request.

This flowchart illustrates the validation logic required for batch removal.
Sources: src/Service/Suppressions/Batch.php:36-40

Batch Constraints

• Limit: Batch operations are restricted to a maximum of 100 entries per call.
• Removal Logic: When removing suppressions in bulk, you must provide either an array of emails or an array of ids. Providing both or neither triggers an InvalidArgumentException.

Sources: src/Service/Suppressions/Batch.php:19-21, src/Service/Suppressions/Batch.php:36-40, tests/Service/Suppression.php:110-118

Implementation Summary

The Suppressions module provides a structured way to handle email deliverability health. By utilizing the Suppression service, you can automate the handling of bounces or manually intervene to prevent sending to specific recipients. The architecture separates individual and batch logic into distinct service classes to maintain clarity and enforce API-specific validation rules.

Sources: src/Service/Suppression.php , src/Service/Suppressions/Batch.php