Topics & Subscriptions Management
Relevant source files
The following files were used as context for generating this wiki page:
Topics & Subscriptions Management handles the categorization of communications and the individual preferences of contacts. Topics define specific categories of messages, while subscriptions track whether a contact has opted in or out of those categories.
Sources: src/Resend/Topic.cs, src/Resend/IResend.cs:752-755
Topic Architecture
The system represents a communication category through the Topic class. Each topic contains an identifier, a name, a description, and a default subscription behavior.
Data Models
The following table describes the fields within the Topic data structures:
| Field | Type | Description |
|---|---|---|
Id | Guid | Unique identifier for the topic. |
Name | string | Human-readable name of the communication category. |
Description | string | Detailed explanation of what the topic covers. |
SubscriptionDefault | SubscriptionType | The default state (e.g., OptIn, OptOut) for new contacts. |
MomentCreated | DateTime | Timestamp of when the topic was created. |
Sources: src/Resend/Topic.cs:9-31, src/Resend/TopicData.cs:9-29
Topic Relationships
The following diagram shows the relationship between Topics and the data used to create or update them.
This diagram illustrates that TopicData provides the necessary properties to instantiate or modify a Topic.
Sources: src/Resend/Topic.cs, src/Resend/TopicData.cs
Topic Operations
You manage topics using the IResend interface and its implementation in ResendClient.
Managing Lifecycle
- List Topics: Call
TopicListAsyncto retrieve a paginated list of all topics. - Create Topic: Use
TopicCreateAsyncwith aTopicDataobject to define a new category. - Retrieve Topic: Call
TopicRetrieveAsyncwith a specificGuidto get topic details. - Update Topic: Use
TopicUpdateAsyncto modify the name, description, or default subscription of an existing topic. - Delete Topic: Call
TopicDeleteAsyncto remove a topic from the system.
Sources: src/Resend/ResendClient.Topics.cs:10-71, src/Resend/IResend.cs:752-790
API Request Flow
The following sequence diagram represents the communication between the client and the Resend API when managing topics.
This diagram shows the standard request-response pattern for creating and retrieving topics.
Sources: src/Resend/ResendClient.Topics.cs:33-52, tools/Resend.ApiServer/Controllers/TopicController.cs:19-48
Subscription Management
Subscription management links contacts to specific topics. It allows you to query or update the subscription status for a specific contact.
Contact Subscription Actions
- List Contact Topics: Call
ContactListTopicsAsyncto see which topics a specific contact is subscribed to. - Update Contact Topics: Call
ContactUpdateTopicsAsyncwith a list ofTopicSubscriptionobjects to change a contact's preferences.
Sources: src/Resend/IResend.cs:560-575, src/Resend/ResendClient.Contacts.cs:174-204
Subscription Status Update
When you update a contact's topics, the client sends a PATCH request to the contact's topics endpoint.
The flow demonstrates the procedure for modifying a contact's communication preferences.
Sources: src/Resend/ResendClient.Contacts.cs:198-204, src/Resend/IResend.cs:574-575
Webhook Events
The system generates events when topics or subscriptions change. These events are processed via webhooks to synchronize external systems.
- Topic Events:
topic.created,topic.updated, andtopic.deletedevents notify listeners of lifecycle changes. - Subscription Events:
contact.topics.updatedinforms when a contact's preferences change.
Sources: tests/Resend.Webhooks.Tests/WebhookEventConverterTests.cs:253-333
The Topics & Subscriptions Management module provides the foundational tools for managing communication categories and respecting recipient preferences. By using the IResend interface, developers can integrate these preference controls directly into their application workflows.