Audiences, Contacts & Segments
Relevant source files
The following files were used as context for generating this wiki page:Contacts represent individual email recipients within the Resend ecosystem. Segments organize these contacts into specific groups for targeted messaging. While the system originally included Audiences, this component is now obsolete and replaced by Segments for contact management and filtering.
Sources: src/Resend/IResend.cs:423, src/Resend/IResend.cs:460
Contacts
The Contact system manages individual recipient data, including email addresses, names, and subscription statuses. You can create, retrieve, update, and delete contacts using either a unique identifier (GUID) or their email address.
Contact Management Operations
The ResendClient provides several methods to manage the contact lifecycle:
- Create: Adds a new contact to the system. The email address must be non-null.
- Retrieve: Fetches contact details via
ContactRetrieveAsync(using GUID) orContactRetrieveByEmailAsync. - Update: Modifies existing contact information.
- Delete: Removes a contact from the system.
Sources: src/Resend/ResendClient.Contacts.cs:11-85, src/Resend/IResend.cs:460-530
Pagination and Listing
When listing contacts, the API uses a paginated query system. You can control the results using the PaginatedQuery object.
| Parameter | Type | Description |
|---|---|---|
Limit | int? | Number of records to return per page. |
Before | string? | A cursor for use in backward pagination. |
After | string? | A cursor for use in forward pagination. |
Sources: src/Resend/ResendClient.Contacts.cs:91-112, src/Resend/IResend.cs:540-547
Segments
Segments provide a way to group contacts dynamically. Unlike the obsolete Audience system, Segments allow for more granular categorization and listing of contacts within specific groups.
The following diagram illustrates the relationship between Contacts and Segments:
This diagram shows that contacts can belong to multiple segments, and segments contain multiple contacts.
Sources: src/Resend/ResendClient.Segments.cs:1-85, src/Resend/IResend.cs:720-770
Segment Operations
| Operation | Method | Description |
|---|---|---|
| Create | SegmentCreateAsync | Initializes a new segment with provided data. |
| List | SegmentListAsync | Retrieves a paginated list of all segments. |
| Retrieve | SegmentRetrieveAsync | Gets details for a specific segment ID. |
| Update | SegmentUpdateAsync | Changes properties of an existing segment. |
| Delete | SegmentDeleteAsync | Removes a segment definition. |
Sources: src/Resend/ResendClient.Segments.cs:33-72, src/Resend/IResend.cs:720-760
Contact Categorization and Topics
Contacts can be further categorized through segment membership and topic subscriptions. Topic subscriptions track whether a contact has opted in or out of specific communication themes.
Workflow: Adding Contact to Segment
The following sequence diagram describes the process of associating a contact with a segment:
This diagram visualizes the API call flow when associating a contact with a segment.
Sources: src/Resend/ResendClient.Contacts.cs:159-165, src/Resend/IResend.cs:567-575
Topic Subscriptions
Contacts manage their communication preferences through topics. You can list a contact's topics or update their subscription status (e.g., Opt-In or Opt-Out).
ContactListTopicsAsync: Retrieves all topics for a specific contact.ContactUpdateTopicsAsync: Updates the list of topic subscriptions for a contact.
Sources: src/Resend/ResendClient.Contacts.cs:178-207, src/Resend/IResend.cs:585-600
Obsolete Audience System
The Audience methods in IResend are marked with the [Obsolete] attribute. Developers should migrate to using Segments for all list management needs.
AudienceAddAsync: Obsolete. Use Segments.AudienceRetrieveAsync: Obsolete. Use Segments.AudienceListAsync: Obsolete. Use Segments.
Sources: src/Resend/IResend.cs:410-458
Implementation Example
The following code illustrates how to create a segment and list the contacts belonging to it:
// List all contacts within a specific segment
var segmentId = Guid.Parse("...");
var query = new PaginatedQuery { Limit = 10 };
var response = await resend.SegmentListContactsAsync(segmentId, query);
foreach (var contact in response.Content.Data)
{
Console.WriteLine(contact.Email);
}
Sources: src/Resend/ResendClient.Segments.cs:75-99, tests/Resend.Tests/ResendClientTests.Segment.cs:31-40
Summary
The Resend .NET SDK provides a robust set of tools for managing recipient data through Contacts and Segments. Contacts serve as the base identity for emails, while Segments offer a modern replacement for the obsolete Audience system to group and filter recipients effectively. Topic subscriptions allow for fine-grained control over recipient preferences, ensuring compliance and targeting precision.