Contact Segments & Topics
Relevant source files
The following files were used as context for generating this wiki page:
Contact Segments and Topics manage groups of recipients and their subscription preferences within the Resend platform. Segments categorize contacts into specific audiences, while Topics control granular communication preferences, such as newsletters or product updates. These components work together to ensure targeted delivery and compliance with user subscription choices.
The system uses a nested architecture where a Contacts instance contains specialized sub-modules for managing segment associations and topic subscriptions for individual contacts.
Architecture and Data Relationships
The Contacts class serves as the primary entry point, delegating specific operations to ContactSegments and ContactTopics. Global definitions for these entities are managed via top-level Segments and Topics modules.
Component Relationship Diagram
The following diagram illustrates how segments and topics relate to the core contact entity.
Segments Management
Segments allow for the categorization of contacts. The SDK supports global segment management (creation and deletion) and contact-specific segment associations.
Contact-Segment Operations
The ContactSegments module handles the relationship between a contact and a segment. You must provide either a contactId or an email to identify the contact for these operations.
- List Segments: Retrieves all segments associated with a specific contact.
- Add Segment: Associates a contact with a specific segment ID.
- Remove Segment: Dissociates a contact from a specific segment.
Sources: src/contacts/segments/contact-segments.ts:23-88, src/contacts/segments/contact-segments.spec.ts:25-45
Sequence: Adding a Contact to a Segment
The following sequence shows the flow when adding a segment to an existing contact.
Topics and Subscriptions
Topics manage the specific types of content a contact receives. Each topic has a defaultSubscription status, which can be opt_in or opt_out.
Global Topic Attributes
| Attribute | Type | Description |
|---|---|---|
id | string | Unique identifier for the topic |
name | string | Display name of the topic |
description | string | Optional text describing the topic purpose |
defaultSubscription | string | Default status for new contacts (opt_in or opt_out) |
Sources: src/topics/topics.ts:25-39, src/topics/topics.spec.ts:27-31
Contact Subscription Updates
The ContactTopics.update() method modifies a contact's subscription status for one or more topics. This is an atomic operation that accepts an array of topic objects containing the topic ID and the desired subscription state.
// Example: Updating subscriptions
await resend.contacts.topics.update({
email: 'user@example.com',
topics: [
{ id: 'topic_123', subscription: 'opt_in' },
{ id: 'topic_456', subscription: 'opt_out' }
]
});
Sources: src/contacts/topics/contact-topics.ts:22-44, src/contacts/topics/contact-topics.spec.ts:108-124
Legacy vs. Current API
The SDK maintains backward compatibility for audienceId, which is now deprecated in favor of the segments property.
- Deprecated Behavior: Using
audienceIdtargets the legacy audience-based contact creation. - Restriction: You cannot use
audienceIdsimultaneously withsegmentsortopics. Attempting to do so returns aninvalid_parametererror. - Current Standard: Create contacts using the
/contactsendpoint with an array ofsegmentsandtopics.
Sources: src/contacts/contacts.ts:48-61, src/contacts/contacts.spec.ts:132-155
Conclusion
Contact Segments and Topics provide the structural foundation for audience management in Resend. By separating contact categorization (Segments) from communication preferences (Topics), the system enables complex targeting while respecting user-level subscription settings. Developers should transition from legacy audienceId implementations to the multi-segment and topic-aware methods provided in the current Contacts API.