Contact Imports & Segments
Relevant source files
The following files were used as context for generating this wiki page:
The Contact Imports and Segments modules manage the bulk ingestion of contact data and the logical grouping of contacts within the Resend platform. Contact Imports allow users to upload CSV files to create or update multiple contacts simultaneously, while Segments facilitate organization and targeted communication.
These modules operate within the resend.Contacts namespace. Imports handle asynchronous processing of large datasets, whereas Segment associations manage the relationships between existing contacts and specific audience groups.
Sources: resend/contacts/_contacts.py:46-51, resend/contacts/imports/_contact_imports.py:21-23
Contact Imports
Contact Imports facilitate the asynchronous ingestion of contact data from CSV files. This system supports mapping CSV columns to contact fields, handling conflicts (upsert or skip), and automatically assigning imported contacts to segments or topics.
Data Flow for Imports
The import process involves a multipart form-data upload of a CSV file. The SDK prepares this data by encoding optional parameters like column_map, segments, and topics into JSON strings before submission.
The diagram shows the sequence from user input to retrieving the status of an asynchronous import job.
Sources: resend/contacts/imports/_contact_imports.py:84-100
Import Parameters and Configuration
The CreateParams structure defines how the system processes the CSV file.
| Parameter | Type | Description |
|---|---|---|
file | bytes | CSV file content (Max 50MB). Required. |
filename | str | Name for the multipart upload. Default: 'import.csv'. |
column_map | Dict[str, Any] | Maps contact fields to CSV column names. |
on_conflict | Literal | Strategy for existing contacts: 'upsert' or 'skip'. |
segments | List[Dict] | List of segment UUIDs to join. |
topics | List[Dict] | List of topic subscriptions. |
Sources: resend/contacts/imports/_contact_imports.py:44-78
Import Job Monitoring
Once an import is created, its status can be tracked via the get method. Completed or failed imports include a counts object with row-level statistics.
# Monitoring an import job
import_status = resend.Contacts.Imports.get("import_id")
print(f"Status: {import_status['status']}")
if "counts" in import_status:
print(f"Total: {import_status['counts']['total']}")
print(f"Created: {import_status['counts']['created']}")
Sources: resend/contacts/imports/_contact_import.py:10-44, examples/contact_imports.py:47-49
Segments Management
Segments serve as organizational units for contacts. While the legacy audience_id approach is still supported, the modern Segments sub-API provides more granular control over contact-to-segment associations.
Contact-Segment Associations
The ContactSegments class manages the lifecycle of a contact's membership in a segment. Associations can be created or removed using either a contact_id or an email.
The sequence diagram illustrates the interaction between the SDK and API when adding a contact to a segment.
Sources: resend/contacts/segments/_contact_segments.py:165-180
Segment API Methods
The system provides both synchronous and asynchronous methods for segment operations.
| Method | Action | Key Parameters |
|---|---|---|
add | Joins a contact to a segment | segment_id, contact_id or email |
remove | Removes a contact from a segment | segment_id, contact_id or email |
list | Lists all segments for a contact | contact_id or email |
Sources: resend/contacts/segments/_contact_segments.py:165-225
Global vs. Audience Contacts
The Contacts module distinguishes between global contacts and audience-specific contacts. If an audience_id is omitted during contact creation or update, the system treats the contact as "Global," which supports custom properties.
- Global Contacts: Support the
propertiesfield for custom metadata. - Audience Contacts: Tied to a specific audience/segment; do not support the properties field during standard contact creation via
/audiences/{id}/contacts.
Sources: resend/contacts/_contacts.py:186-210, examples/contacts_global.py:1-25
Conclusion
The Contact Imports and Segments systems provide a robust framework for managing large-scale contact data. Imports handle the complexity of bulk CSV processing and conflict resolution, while Segments offer a flexible way to group contacts for targeted operations. Both systems support synchronous and asynchronous execution to accommodate different application architectures.