Subscription Topics
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/topics/Topics.java
- src/main/java/com/resend/services/contacts/ContactTopics.java
- src/main/java/com/resend/services/topics/model/Topic.java
- src/main/java/com/resend/services/topics/model/AbstractTopic.java
- src/main/java/com/resend/services/topics/model/CreateTopicOptions.java
- src/main/java/com/resend/services/contacts/model/UpdateContactTopicsOptions.java
- src/main/java/com/resend/services/contacts/Contacts.java
Subscription Topics allow you to categorize communications and manage contact preferences for specific types of content. The Resend Java SDK provides a dedicated service to manage these topics globally and a sub-service within the Contacts module to handle individual contact subscriptions.
Sources: src/main/java/com/resend/services/topics/Topics.java, src/main/java/com/resend/services/contacts/Contacts.java:41-43
Topic Management Architecture
The system distinguishes between the definition of a topic and a contact's subscription to that topic. The Topics service manages the global lifecycle of topics, while the ContactTopics service manages the relationship between contacts and those topics.
Core Topic Entities
The following diagram illustrates the relationship between the base topic attributes and the specific models used in the SDK.
The AbstractTopic class defines the fundamental properties of a topic, including its unique identifier, human-readable name, and default subscription behavior (e.g., "opt_in" or "opt_out").
Sources: src/main/java/com/resend/services/topics/model/AbstractTopic.java:9-70, src/main/java/com/resend/services/topics/model/Topic.java:7-27
Global Topic Operations
The Topics service interacts with the /topics endpoint to perform CRUD operations on topics.
| Operation | Method | Endpoint | Description |
|---|---|---|---|
| Create | create(CreateTopicOptions) | POST /topics | Creates a new communication topic. |
| Get | get(String) | GET /topics/{id} | Retrieves details for a specific topic. |
| Update | update(String, UpdateTopicOptions) | PATCH /topics/{id} | Modifies topic metadata. |
| Remove | remove(String) | DELETE /topics/{id} | Deletes a topic from the system. |
| List | list(ListParams) | GET /topics | Retrieves a paginated list of topics. |
Sources: src/main/java/com/resend/services/topics/Topics.java:36-105
Creating Topics
When you create a topic, you must specify a name and a default subscription preference.
CreateTopicOptions options = CreateTopicOptions.builder()
.name("Product Updates")
.defaultSubscription("opt_in")
.description("Notifications about new features")
.build();
Sources: src/main/java/com/resend/services/topics/model/CreateTopicOptions.java:72-113
Contact Topic Subscriptions
Managing contact-specific preferences is handled through the ContactTopics service, accessible via contacts().topics().
Listing Subscriptions
You can retrieve all topics and their current subscription status for a specific contact using either their contactId or email.
Sources: src/main/java/com/resend/services/contacts/ContactTopics.java:43-69
Updating Subscriptions
To update preferences, the actor provides a list of ContactTopicOptions containing the topic ID and the desired action (opt_in or opt_out).
During updates, the SDK validates that either an id or email is provided, but not both. It then serializes only the topics array as the request payload.
Sources: src/main/java/com/resend/services/contacts/ContactTopics.java:77-94, src/main/java/com/resend/services/contacts/model/UpdateContactTopicsOptions.java:18-35
Data Models
Contact Topic Model
The ContactTopic model represents the status of a specific topic for an individual contact.
| Field | Type | Description |
|---|---|---|
id | String | The unique ID of the topic. |
name | String | The display name of the topic. |
description | String | A brief explanation of the topic content. |
subscription | String | The current status: opt_in or opt_out. |
Sources: src/main/java/com/resend/services/contacts/model/ContactTopic.java:10-24
Contact Import Subscriptions
During bulk contact imports, you can apply specific topic subscriptions to all contacts in the import using the ContactImportTopicSubscription class. This is currently part of the Beta Imports service.
Sources: src/main/java/com/resend/services/contacts/model/ContactImportTopicSubscription.java:8-25, src/main/java/com/resend/services/contacts/model/CreateContactImportOptions.java:23-45
Conclusion
Subscription Topics provide a granular way to manage communication preferences. By using the Topics service for global definitions and the ContactTopics service for individual preferences, developers can ensure that contacts only receive the content they have opted into, improving deliverability and compliance.