Contact Imports

Relevant source files

The following files were used as context for generating this wiki page:

• contact_imports.go
• examples/contact_imports.go
• contact_imports_test.go
• examples/contacts.go
• contact_topics.go

The Contact Imports module enables bulk creation and synchronization of contacts by processing CSV files. It supports mapping custom columns, handling conflicts, and automatically assigning contacts to specific Segments or subscribing them to Topics.

This feature operates asynchronously. You upload a file to initiate an import task, then track its progress through status updates and count summaries.

Core Architecture and Data Flow

The system uses a multipart form-data request to transmit CSV files and metadata to the Resend API. The ContactImportsSvc interface defines the primary methods for managing these tasks.

The diagram shows the asynchronous flow from the initial file upload to the monitoring of the import task.
Sources: contact_imports.go:88-95, examples/contact_imports.go:17-48

Key Data Structures

The module relies on several structures to define the import behavior and capture the results.

Structure	Description
ContactImport	Represents an import task including its ID, current status, and timestamps.
CreateContactImportRequest	Contains the CSV byte data, filename, conflict strategy, and column mapping.
ContactImportCounts	Provides metrics on processed records: total, created, updated, skipped, and failed.
ContactImportStatus	An enumeration of task states: queued, in_progress, completed, and failed.

Sources: contact_imports.go:17-43, contact_imports.go:50-67

Import Task Management

Creating an Import

To start an import, you must provide a CSV file. The file size is limited to a maximum of 50MB. You can optionally define a ColumnMap to link CSV headers to contact fields like email, first_name, and last_name.

createParams := &resend.CreateContactImportRequest{
    File:       file,
    Filename:   "contacts.csv",
    OnConflict: "upsert",
    ColumnMap: map[string]any{
        "email":      "Email",
        "first_name": "First Name",
    },
}
created, err := client.Contacts.Imports.Create(createParams)

Sources: contact_imports.go:52-58, examples/contact_imports.go:26-38

Conflict Resolution

The OnConflict field determines how the system handles existing contacts:

• skip: (Default) Ignores the incoming record if the contact already exists.
• upsert: Updates the existing contact details with information from the CSV.

Sources: contact_imports.go:61, contact_imports_test.go:42-43

Integration with Segments and Topics

Imports can automatically organize contacts during the processing phase.

• Segments: You provide a list of ContactImportSegment IDs to add all imported contacts to specific groups.
• Topics: You provide TopicSubscriptionUpdate objects to set subscription preferences (e.g., opt_in) for specific topics.

Sources: contact_imports.go:46-48, contact_imports.go:63-66, examples/contact_imports.go:43-46

Monitoring and Retrieval

Since imports are asynchronous, the API provides methods to check the status and summary of processing.

The sequence diagram illustrates the polling or retrieval of import task status.
Sources: contact_imports.go:128-140, contact_imports_test.go:96-105

Filtering and Pagination

The List method allows retrieving multiple import tasks. You can filter results by Status and control the output using Limit, After, and Before parameters for cursor-based pagination.

Sources: contact_imports.go:74-80, contact_imports.go:157-170

Implementation Details

The SDK implements a specialized NewMultipartRequest helper to handle the binary file upload. This function constructs the multipart/form-data body, writes the file bytes into a form field named file, and serializes the metadata fields (like column_map and topics) into string fields.

This diagram depicts the relationship between the service interface and its implementation.
Sources: contact_imports.go:82-89, contact_imports.go:193-205

Conclusion

Contact Imports provide a robust mechanism for managing large-scale contact data. By supporting complex column mapping and direct integration with Segent and Topic systems, it serves as the primary tool for synchronizing external databases with the Resend platform.