Contacts & Imports

Relevant source files

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

• src/contacts/contacts.ts
• src/contacts/imports/contact-imports.ts
• src/contacts/topics/contact-topics.ts
• src/contact-properties/contact-properties.ts
• src/contacts/imports/interfaces/create-contact-import.interface.ts
• src/contacts/contacts.integration.spec.ts
• src/contacts/imports/contact-imports.spec.ts

The Contacts & Imports system manages individual recipient data, custom metadata, and bulk data ingestion within the Resend platform. It provides tools for creating, updating, and segmenting contacts, as well as an asynchronous import engine for processing large datasets via CSV or file uploads.

This module organizes data into four primary sub-modules: core Contacts, bulk Imports, subscription Topics, and custom Contact Properties.

Module Architecture

The Contacts class serves as the primary entry point for all contact-related operations. It utilizes composition to provide access to specialized sub-modules for imports, topics, and segments.

Contact Management

The system supports standard CRUD operations for managing individual contacts. It handles a transition from legacy audience-based structures to modern segment and topic associations.

Creating Contacts

The create method accepts either modern CreateContactOptions or LegacyCreateContactOptions. If you provide audienceId, the system routes the request to the legacy endpoint /audiences/{id}/contacts. If you provide segments or topics, the system uses the /contacts endpoint.

Validation Logic:

• If you use audienceId, you cannot use segments or topics simultaneously.
• If you attempt to mix these parameters, the system returns an invalid_parameter error.

Sources: src/contacts/contacts.ts:55-103

Retrieving and Listing Contacts

You can retrieve contacts using a unique ID or an email address. The get, update, and remove methods determine the correct API path based on whether an audienceId is present.

Operation	Identifier Type	Target Endpoint
Get (Current)	ID or Email	/contacts/{id_or_email}
Get (Legacy)	ID or Email + Audience ID	/audiences/{audience_id}/contacts/{id_or_email}
List	Segment ID or Audience ID	/segments/{segment_id}/contacts

Sources: src/contacts/contacts.ts:105-180

Bulk Contact Imports

The ContactImports sub-module handles bulk recipient data ingestion. Unlike standard contact operations that use JSON, the import system uses multipart/form-data to transfer large files.

Import Workflow

1. You provide a Blob file and a columnMap.
2. The system builds a FormData object.
3. The API processes the file asynchronously.
4. You monitor progress via the get(id) method.

Import Configuration

The import process is controlled by several key parameters defined in the CreateContactImportOptions interface.

Parameter	Type	Description
file	Blob	The CSV or text file containing contact data.
columnMap	Object	Maps file headers (e.g., "First Name") to system fields (firstName).
onConflict	'upsert' | 'skip'	Determines behavior when a contact email already exists.
segments	Array	List of segment IDs to associate with imported contacts.
topics	Array	List of topics and subscription statuses (opt_in/opt_out).

Sources: src/contacts/imports/interfaces/create-contact-import.interface.ts:25-31, src/contacts/imports/contact-imports.ts:71-89

Contact Topics and Subscriptions

The ContactTopics sub-module manages the subscription relationship between a contact and specific communication channels (topics).

• Listing: Retrieves all topics associated with a contact via /contacts/{identifier}/topics.
• Updating: Modifies a contact's subscription status for one or more topics. Statuses are restricted to opt_in or opt_out.

Sources: src/contacts/topics/contact-topics.ts:22-68, src/contacts/topics/contact-topics.spec.ts:16-36

Contact Properties

Custom metadata is managed through ContactProperties. This system allows you to define schema-like properties that can be attached to any contact.

Property Data Types

When defining a contact property, you must specify a valid ContactImportPropertyType. Supported types include:

• string
• number
• boolean

Sources: src/contacts/imports/interfaces/create-contact-import.interface.ts:4, src/contact-properties/contact-properties.spec.ts:89-97

Integration Summary

The Contacts & Imports system enables precise audience management by combining individual record control with powerful bulk processing. By supporting legacy audience structures alongside modern segments and topics, it ensures backward compatibility while providing the architecture needed for complex email marketing workflows. Individual contacts are managed via JSON-based REST endpoints, while the import engine utilizes multipart data transfer for efficient handling of external datasets.

Sources: src/contacts/contacts.ts, src/contacts/imports/contact-imports.ts, src/contacts/contacts.integration.spec.ts