Bulk Contact Imports
Relevant source files
The following files were used as context for generating this wiki page:
- 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/ContactImportColumnMap.java
- src/main/java/com/resend/services/contacts/model/ContactImportPropertyMapping.java
- src/main/java/com/resend/services/contacts/model/ContactImportTopicSubscription.java
- src/test/java/com/resend/services/util/ContactImportsUtil.java
Bulk Contact Imports allow you to add multiple contacts to your Resend account simultaneously by uploading a CSV file. This feature is currently in beta and handles the asynchronous processing of contact data, including field mapping, segment assignment, and topic subscriptions.
Sources: ContactImports.java:23-27, CreateContactImportOptions.java:22-26
Import Process Architecture
The system uses a multipart form-data request to transmit CSV files and configuration metadata to the Resend API. The ContactImports service manages the lifecycle of an import, from initial creation to status retrieval.
Data Flow Overview
The following diagram illustrates the lifecycle of a contact import request:
The SDK prepares the request by serializing complex objects like ContactImportColumnMap into JSON strings before attaching them as form fields in the multipart request.
Sources: ContactImports.java:65-103, CreateContactImportOptions.java:16-20
Import Configuration
You configure an import using the CreateContactImportOptions class. This class defines the file source, conflict handling, and metadata mapping.
File Specifications
Imports support three input methods for CSV data:
- File: Direct upload from the local filesystem.
- Byte Array: Raw bytes for in-memory CSV data.
- InputStream: Streaming data read into memory during the build process.
The maximum supported file size is 50MB.
Sources: CreateContactImportOptions.java:31-33, CreateContactImportOptions.java:132-152
Mapping and Logic
The import logic depends on the following parameters:
| Parameter | Type | Description |
|---|---|---|
columnMap | ContactImportColumnMap | Maps CSV headers to contact fields (Email, First Name, etc.). |
onConflict | String | Strategy for existing contacts: "upsert" or "skip". |
segments | List<ContactImportSegmentReference> | Segments to which all imported contacts will be added. |
topics | List<ContactImportTopicSubscription> | Topic subscriptions applied to all imported contacts. |
Sources: CreateContactImportOptions.java:54-72, ContactImportColumnMap.java:15-32
Custom Property Mapping
The ContactImportColumnMap identifies which CSV columns correspond to standard contact fields and custom properties. Custom properties require a ContactImportPropertyMapping which specifies the column name and the data type.
Valid types for custom properties include "string", "number", and "boolean". If no type is specified, the API defaults to "string".
Sources: ContactImportColumnMap.java:34-45, ContactImportPropertyMapping.java:13-18, ContactImportPropertyMapping.java:85-93
Tracking Import Progress
Because imports are processed asynchronously, the API provides status updates and statistical counts.
Import Counts Model
The ContactImportCounts object tracks the results of the processing:
- Total: Number of contacts found in the file.
- Created: Number of new contacts added.
- Updated: Number of existing contacts modified (if using
upsert). - Skipped: Number of contacts ignored due to conflicts or errors.
- Failed: Number of contacts that could not be processed.
Sources: ContactImportsUtil.java:55-62, ContactImportsTest.java:34-36
Listing Imports
You can retrieve a list of previous imports using the list method. This supports pagination via ListContactImportsParams and filtering by status.
Sources: ContactImports.java:125-142
Usage Example
The following snippet demonstrates setting up a complete import request with mapping and topic subscriptions:
ContactImportColumnMap columnMap = ContactImportColumnMap.builder()
.email("Email")
.firstName("First Name")
.property("plan", ContactImportPropertyMapping.builder()
.column("Plan")
.type("string")
.build())
.build();
CreateContactImportOptions options = CreateContactImportOptions.builder()
.file(new File("contacts.csv"))
.columnMap(columnMap)
.onConflict("upsert")
.topics(ContactImportTopicSubscription.builder()
.id("topic_uuid")
.subscription("opt_in")
.build())
.build();
CreateContactImportResponseSuccess response = resend.contacts().imports().create(options);
Sources: ContactImportsUtil.java:30-49, ContactImports.java:65-68
Summary
The Bulk Contact Import module provides a structured way to ingest large volumes of contact data via CSV. By combining multipart file uploads with JSON-serialized mapping configurations, it allows for complex data synchronization, including custom contact properties and automated membership in segments and topics.