Suppressions Management

Relevant source files

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

• suppressions.go
• examples/suppressions.go
• suppressions_test.go
• examples/with_pagination.go
• examples/contacts.go
• CHANGELOG.md

Suppressions Management provides the tools to manage email addresses that should not receive communications. This system tracks addresses that have bounced, complained, or been manually added to a blocklist to protect sender reputation and comply with anti-spam regulations.

The module allows for single and batch operations to add, retrieve, list, and remove suppressions. It integrates with the broader Resend ecosystem, alongside related modules like Contacts and Segments, to ensure that delivery attempts are automatically filtered against the suppression list. Sources: suppressions.go, examples/suppressions.go

Core Data Structures

The suppression system uses specific types to define the origin of a suppression and the data returned by the API.

Suppression Origins

The SuppressionOrigin type identifies why an email was suppressed. There are three valid origins:

• bounce: The email address resulted in a hard bounce.
• complaint: The recipient marked the email as spam.
• manual: The address was added to the list by a user.

Sources: suppressions.go:10-16

Suppression Objects

The SDK defines two primary structures for suppression data: Suppression (returned by Get) and SuppressionListEntry (returned by List).

Field	Type	Description
Id	string	Unique UUID for the suppression entry.
Email	string	The suppressed email address.
Origin	SuppressionOrigin	The reason for suppression (bounce, complaint, manual).
SourceId	*string	ID of the event causing suppression (null for manual).
CreatedAt	string	Timestamp when the suppression was created.
Object	string	Only present in Suppression struct; identifies the object type.

Sources: suppressions.go:18-42

Suppression Operations

The SuppressionsSvc interface defines the methods available for managing individual suppression entries.

Adding Suppressions

Adding an email address is an upsert operation. The API trims and lowercases the email address before processing. If you add an already-suppressed address, the API returns the existing suppression ID. Sources: suppressions.go:94-97

Retrieving and Removing

You can retrieve or remove a suppression using either its unique ID or the email address itself. The SDK handles URL path escaping for identifiers containing special characters like + or /. Sources: suppressions.go:166-170, suppressions_test.go:281-295

Batch Operations

The SuppressionsBatchSvc allows processing up to 100 email addresses in a single request.

• Batch Add: Accepts a list of strings. The API dedupes the input and performs an upsert. The returned data may be shorter than the input list if duplicates were provided. Sources: suppressions.go:222-226
• Batch Remove: Accepts either a list of emails or a list of ids, but not both. Unlike single removal, identifiers that do not exist in the suppression list do not cause an error; the response only includes entries that were successfully deleted. Sources: suppressions.go:248-253

Filtering and Pagination

The List operation supports filtering by origin and uses cursor-based pagination.

Parameter	Type	Description
Origin	SuppressionOrigin	Filter by bounce, complaint, or manual.
Limit	*int	Number of results to return (default is 20).
After	*string	Cursor for fetching the next page of results.
Before	*string	Cursor for fetching the previous page of results.

Sources: suppressions.go:50-57, examples/with_pagination.go:81-90

Implementation Details

The following Mermaid diagram illustrates the class hierarchy for the suppressions service within the resend.Client.

Context Support

Every service method has a WithContext variant (e.g., AddWithContext). These allow for cancellation and timeout management. If a context is cancelled before the request completes, the SDK returns a context.Canceled error. Sources: suppressions.go:102, suppressions_test.go:497-550

Error Handling

The SDK performs basic validation before initiating network requests:

1. Add requires an email address. Sources: suppressions.go:103
2. Get and Remove require an ID or email. Sources: suppressions.go:171
3. Batch.Remove fails if both Emails and Ids are provided, or if both are empty. Sources: suppressions.go:255-259

Suppressions Management ensures robust compliance and sender reputation by centralizing the lifecycle of email blocklists, providing efficient single and batch interfaces for developers.