Contact Management
Relevant source files
The following files were used as context for generating this wiki page:- src/main/java/com/resend/services/contacts/Contacts.java
- src/main/java/com/resend/services/contacts/model/Contact.java
- src/main/java/com/resend/services/contacts/model/CreateContactOptions.java
- src/main/java/com/resend/services/contacts/ContactSegments.java
- src/main/java/com/resend/services/contacts/ContactTopics.java
- src/main/java/com/resend/services/contacts/ContactImports.java
- src/main/java/com/resend/services/contacts/model/CreateContactImportOptions.java
- src/main/java/com/resend/services/contacts/model/UpdateContactOptions.java
Contact Management handles the lifecycle and categorization of recipients within the Resend ecosystem. The module provides functionality to create, update, and remove global contacts, as well as specialized sub-services for managing segment memberships, topic subscriptions, and bulk CSV imports.
The system distinguishes between Global Contacts, which exist independently of any grouping, and their associations with Segments (for targeted filtering) or Topics (for subscription management).
Sources: src/main/java/com/resend/services/contacts/Contacts.java:13-35
Core Architecture
The Contacts class serves as the primary entry point for the module. It inherits from BaseService and provides access to three specialized sub-services:
- ContactSegments: Manages membership in specific segments.
- ContactTopics: Manages opt-in/opt-out preferences for various communication topics.
- ContactImports: Handles bulk contact ingestion via multipart CSV uploads.
Service Structure Diagram
The following diagram illustrates the relationship between the main Contacts service and its specialized sub-services.
Contact Lifecycle
Contacts are typically managed through standard CRUD operations. The Resend API requires a two-step workflow for segment-specific contacts: you first create a global contact and then add it to a segment.
Global Operations
| Operation | Method | Description |
|---|---|---|
| Create | create(CreateContactOptions) | Registers a new global contact. Ignores segmentId in options. |
| Retrieve | get(String) | Fetches a contact by ID or email address. |
| List | list(ListParams) | Retrieves contacts with support for pagination. |
| Update | update(UpdateContactOptions) | Modifies existing contact details or custom properties. |
| Delete | remove(String) | Removes a contact by ID. |
Sources: src/main/java/com/resend/services/contacts/Contacts.java:107-268, src/main/java/com/resend/services/contacts/model/CreateContactOptions.java:12-20
Segment Association Flow
This sequence diagram shows the required steps to associate a new contact with a specific segment.
Contact Data Model
The Contact object represents the entity in the system, containing identity, subscription status, and creation metadata.
Data Fields
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the contact. |
email | String | The contact's email address. |
firstName | String | The contact's first name. |
lastName | String | The contact's last name. |
unsubscribed | Boolean | Indicates if the contact has opted out of communications. |
properties | Map | Key-value pairs for custom contact metadata. |
Sources: src/main/java/com/resend/services/contacts/model/Contact.java:8-33, src/main/java/com/resend/services/contacts/model/CreateContactOptions.java:39-44
Specialized Sub-services
Contact Topics
Manages the preferences of contacts regarding specific communication categories (e.g., "Product Updates").
- Update Strategy: When updating topics, the SDK serializes only the topics array, not the entire options object.
- Identification: Topics can be listed or updated using either the
contactIdor the contactemail.
Sources: src/main/java/com/resend/services/contacts/ContactTopics.java:44-79
Contact Imports
The ContactImports service allows bulk creation or updates of contacts using CSV files. This service is currently in Beta.
- Multipart Requests: The service utilizes
multipart/form-datafor uploads. - File Constraints: Files must not exceed 50MB (
MAX_FILE_SIZE_BYTES). - Conflict Resolution: Supports
upsertorskipstrategies for existing contacts. - Mapping: Requires a
ContactImportColumnMapto link CSV headers to contact fields (e.g., email, first name, last name).
Sources: src/main/java/com/resend/services/contacts/ContactImports.java:23-32, src/main/java/com/resend/services/contacts/model/CreateContactImportOptions.java:25-45, src/main/java/com/resend/services/contacts/model/CreateContactImportOptions.java:119-125
Implementation Details
Custom Properties
Both CreateContactOptions and UpdateContactOptions support a properties map. Users can set the entire map at once or add individual properties using a fluent property(key, value) method. These properties are serialized into a properties JSON object in the request payload.
Sources: src/main/java/com/resend/services/contacts/model/CreateContactOptions.java:154-177, src/main/java/com/resend/services/contacts/model/UpdateContactOptions.java:160-183
Deprecated Methods
The Contacts service contains several deprecated methods that accepted segmentId or audienceId directly. Architectural updates moved these operations to the ContactSegments sub-service to maintain a cleaner separation of concerns.
Sources: src/main/java/com/resend/services/contacts/Contacts.java:132-154