Suppressions & Topics Management
Relevant source files
The following files were used as context for generating this wiki page:
The Suppressions and Topics Management system provides tools to control email delivery and subscriber preferences. The Suppressions module prevents delivery to specific addresses that have bounced, complained, or been manually blocked. The Topics module categorizes email communications and manages granular opt-in/opt-out statuses for individual contacts.
Sources: resend/suppressions/_suppressions.py, resend/suppressions/_suppression.py, examples/topics.py
Email Suppressions
Suppressions represent email addresses to which Resend will not deliver mail. The system automatically populates this list based on delivery events or allows manual management.
Suppression Architecture
The suppression system distinguishes between single operations and batch operations. It uses an origin field to identify why an address was suppressed.
The diagram shows the flow of requests from the user through the Suppressions classes to the API endpoints.
Sources: resend/suppressions/_suppressions.py:21-25, resend/suppressions/_suppressions.py:88-125
Suppression Data Models
Suppressions use specific data structures for single items and list entries. List entries omit the object field for efficiency.
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier for the suppression. |
email | str | The suppressed email address. |
origin | Literal | Origin of suppression: bounce, complaint, or manual. |
source_id | Optional[str] | ID of the event causing suppression (e.g., a specific email ID). None for manual. |
created_at | str | ISO timestamp of creation. |
Sources: resend/suppressions/_suppression.py:12-61
Batch Operations
Batch operations allow managing up to 100 addresses in a single call.
- Batch Add: Normalizes addresses server-side; adding an existing suppression returns the current object.
- Batch Remove: Requires either a list of
emailsorids, but never both.
Sources: resend/suppressions/_suppressions.py:127-140, tests/suppressions_test.py:165-225, examples/suppressions.py:31-43
Topics Management
Topics allow senders to group communications (e.g., "Weekly Newsletter") and manage subscription states.
Topic Lifecycle
You can create, retrieve, update, and delete topics. Each topic has a default_subscription setting that determines the status of contacts who have not explicitly set a preference.
The diagram illustrates the sequence of creating and listing topics via the SDK.
Sources: resend/topics/_topics.py, tests/topics_test.py:11-45
Topic Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | Display name of the topic. |
default_subscription | Literal | Yes | Default state: opt_in or opt_out. |
description | str | No | Internal or external description of the topic. |
Sources: tests/topics_test.py:28-40, examples/topics.py:10-15
Contact Topic Subscriptions
Contact Topic management connects specific contacts to topics with an explicit subscription status.
Subscription Statuses
Contacts can have one of two statuses for a topic:
- opt_in: The contact explicitly chose to receive mail for this topic.
- opt_out: The contact explicitly chose to stop receiving mail for this topic.
Sources: tests/contact_topics_test.py:15-25
Implementation Logic
- List Subscriptions: Retrieve all topics for a contact using their
contact_idoremail. - Update Subscriptions: Change the status of multiple topics for a single contact in one request.
- Identifier Encoding: Email identifiers are URL-encoded before being sent to the API.
# Example: Updating a contact's topic preferences
params: ContactsTopics.UpdateParams = {
"email": "user@example.com",
"topics": [
{"id": "topic_1", "subscription": "opt_in"},
{"id": "topic_2", "subscription": "opt_out"},
],
}
resend.Contacts.Topics.update(params)
Sources: tests/contact_topics_test.py:116-130, resend/suppressions/_suppressions.py:117-120
Error Handling and Constraints
- NoContentError: Raised if the API returns a success status but empty content when a response body was expected.
- ValueError: Raised if required identifiers (like
idoremail) are missing or if invalid combinations of batch parameters are provided. - Pagination: Listing suppressions or topics supports
limit,before, andafterparameters for cursor-based navigation.
Sources: tests/topics_test.py:47-51, tests/suppressions_test.py:227-231, resend/suppressions/_suppressions.py:108-112
Summary
The system ensures high deliverability by managing automated and manual suppressions. It simultaneously provides a flexible subscription framework through Topics, allowing contacts to manage their own communication preferences at a granular level. Management is available through both synchronous and asynchronous methods in the SDK.
Sources: resend/suppressions/_suppressions.py:142-214, tests/topics_async_test.py:14-25