Topics Management

Relevant source files

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

• topics.go
• examples/topics.go
• contact_topics.go
• examples/contacts.go
• topics_test.go
• contact_topics_test.go
• examples/send_email.go
• CHANGELOG.md

Topics Management allows you to organize email content into categories and manage recipient subscription preferences. This system ensures compliance by tracking whether contacts opt in or out of specific communication types, such as newsletters or product updates.

Introduced in version 3.0.0, the Topics API provides a structured way to handle global subscription states and per-contact overrides. You use the Topics service for administrative management and the Contacts.Topics sub-service to manage individual subscriber preferences.

Sources: CHANGELOG.md:15, topics.go:53-66

Architecture and Data Structures

The system relies on a set of core data structures that define the behavior of a topic and its relationship with contacts.

Core Topic Entities

A Topic serves as the primary category for communication. It defines a DefaultSubscription status which determines the state of recipients who have not explicitly set a preference.

The diagram shows the relationship between a global Topic definition and how it manifests as a specific subscription for a contact.

Sources: topics.go:10-13, topics.go:27-33, contact_topics.go:11-16

Data Fields Summary

Field	Type	Description
Name	string	The display name of the topic. Max 50 characters.
Description	string	Optional context for the topic. Max 200 characters.
DefaultSubscription	string	Set to opt_in or opt_out. Permanent after creation.
Subscription	string	The specific state for a contact (opt_in or opt_out).

Sources: topics.go:27-33, examples/topics.go:42-43, contact_topics.go:11-16

Administrative Topic Operations

You manage the lifecycle of topics using the TopicsSvc interface. This service supports standard CRUD operations through the Resend client.

Creating and Updating Topics

When you create a topic, you must specify the name and the default subscription behavior. Note that the DefaultSubscription field cannot be modified once the topic is created.

This flow illustrates the initialization and subsequent modification of a topic.

Sources: topics.go:68-88, examples/topics.go:16-46

Listing and Retrieval

The API supports paginated listing of all topics within a project. You use ListOptions to control the number of results and the cursor position.

Parameter	Type	Description
Limit	*int	Number of topics to return (default 20).
After	*string	Cursor for fetching the next page.
Before	*string	Cursor for fetching the previous page.

Sources: topics.go:119-138, examples/topics.go:66-94

Contact Subscription Management

The Contacts.Topics sub-service manages how individual contacts interact with specific topics. You can query a contact's current subscriptions or update them using their Id or Email.

Subscription Update Logic

When updating subscriptions, you provide an array of TopicSubscriptionUpdate objects. Each object maps a topic ID to a new subscription status.

The sequence demonstrates the process of changing a contact's preference for one or more topics.

Sources: contact_topics.go:37-43, contact_topics.go:94-131, examples/contacts.go:121-137

Integration with Email Sending

Topics control email delivery at the point of sending. By including a TopicId in your SendEmailRequest, the system automatically filters recipients based on their subscription status and the topic's defaults.

Delivery Rules

1. Subscribed Contact: If a recipient is a contact and has explicitly opt_in, the email is delivered.
2. Unsubscribed Contact: If a recipient has explicitly opt_out, the email is not sent and is marked as failed.
3. Non-Contact Recipient: If the recipient is not in your contact list, delivery depends on the topic's DefaultSubscription. If set to opt_in, the email is sent.

Sources: examples/send_email.go:111-125

// Example: Sending email with a topic filter
topicParams := &resend.SendEmailRequest{
    From:    "onboarding@resend.dev",
    To:      []string{"delivered@resend.dev"},
    Subject: "Newsletter",
    TopicId: "topic_uuid_here",
}
sent, err := client.Emails.SendWithContext(ctx, topicParams)

Sources: examples/send_email.go:117-123

Summary

Topics Management provides the necessary tools for maintaining organized communication channels and respecting recipient preferences. By leveraging the Topics service and Contact.Topics sub-service, you ensure that emails are only delivered to recipients who have not opted out of specific categories, thereby maintaining sender reputation and compliance.

Sources: topics.go, contact_topics.go, examples/topics.go