Dynamic Contact Segments
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/segments/Segments.java
- src/main/java/com/resend/services/contacts/ContactSegments.java
- src/main/java/com/resend/services/contacts/model/ContactSegment.java
- src/main/java/com/resend/services/contacts/Contacts.java
- src/main/java/com/resend/services/contacts/model/CreateContactOptions.java
- src/main/java/com/resend/services/contacts/model/ListContactsOptions.java
Dynamic Contact Segments allow you to group contacts into logical sets for targeted communication. The system provides a centralized way to create segments and manage contact memberships through a dedicated sub-service architecture.
Segments were previously known as "audiences" in earlier versions of the SDK. While legacy methods using audienceId are still present for backward compatibility, the current architecture prioritizes the Segments and ContactSegments services for managing these groups.
Sources: src/main/java/com/resend/services/contacts/Contacts.java:23-35, src/main/java/com/resend/services/contacts/model/CreateContactOptions.java:23-30
Service Architecture
The Resend Java SDK organizes segment functionality into two primary services: Segments and ContactSegments. The Segments service handles the lifecycle of the segment itself, while ContactSegments manages the association between contacts and those segments.
Component Relationship
The following diagram illustrates how the Contacts service provides access to segment-related operations.
The Contacts class acts as the entry point, delegating membership tasks to ContactSegments. The standalone Segments class manages the segment entities.
Sources: src/main/java/com/resend/services/contacts/Contacts.java:62-68, src/main/java/com/resend/services/segments/Segments.java:13-16, src/main/java/com/resend/services/contacts/ContactSegments.java:14-17
Managing Segments
The Segments service provides standard CRUD operations for segment entities. You must create a segment before you can add contacts to it.
| Operation | Method | Endpoint | Description |
|---|---|---|---|
| Create | create(CreateSegmentOptions) | POST /segments | Creates a new segment group. |
| Retrieve | get(String id) | GET /segments/{id} | Fetches details of a specific segment. |
| List | list(ListParams) | GET /segments | Retrieves a paginated list of all segments. |
| Update | update(String id, UpdateSegmentOptions) | PATCH /segments/{id} | Modifies segment metadata like name. |
| Delete | remove(String id) | DELETE /segments/{id} | Permanently deletes a segment. |
Sources: src/main/java/com/resend/services/segments/Segments.java:44-106
Contact Membership Operations
The ContactSegments service handles the linking of contacts to segments. You can identify a contact using either its unique ID or its email address.
Adding and Removing Contacts
When adding or removing a contact, you must provide exactly one identifier (id or email) and the target segmentId. Providing both identifiers or omitting both results in an IllegalArgumentException.
The logic ensures data integrity by validating identifiers before making the network call.
Sources: src/main/java/com/resend/services/contacts/ContactSegments.java:46-77
Listing Contact Segments
You can retrieve all segments a specific contact belongs to using the list method. This supports both simple retrieval and paginated results via ListParams.
Sources: src/main/java/com/resend/services/contacts/ContactSegments.java:86-112
Data Models
ContactSegment Object
The system represents a contact's membership using the ContactSegment model, which includes the segment's identity and when the contact was added.
| Field | Type | Description |
|---|---|---|
id | String | The unique identifier for the segment. |
name | String | The display name of the segment. |
created_at | String | Timestamp when the segment was created. |
Sources: src/main/java/com/resend/services/contacts/model/ContactSegment.java:11-30
Membership Conflict Rules
When performing operations through CreateContactOptions or UpdateContactOptions, the SDK explicitly ignores segment_id and audience_id fields. You must use the explicit two-step workflow:
- Create or identify a global contact.
- Use
contacts().segments().add()to manage membership.
Sources: src/main/java/com/resend/services/contacts/model/CreateContactOptions.java:54-65, src/main/java/com/resend/services/contacts/Contacts.java:87-93
Filtering Contacts by Segment
The Contacts service allows listing contacts filtered by a specific segment. When using ListContactsOptions, segmentId takes precedence over the deprecated audienceId.
If no segment identifier is provided in the options, the SDK defaults to fetching global contacts from the /contacts endpoint.
Sources: src/main/java/com/resend/services/contacts/Contacts.java:125-151
Conclusion
Dynamic Contact Segments provide a robust mechanism for organizing contacts. By separating segment management from contact membership, the Resend SDK ensures a clean API that supports granular targeting while maintaining compatibility with legacy audience structures.