Contacts & Audience Management

Relevant source files

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

• src/commands/contacts/index.ts
• src/commands/contacts/create.ts
• src/commands/contacts/imports/create.ts
• src/commands/contacts/utils.ts
• src/commands/topics/index.ts
• skills/resend-cli/references/contacts.md

Contacts & Audience Management handles the storage, organization, and subscription preferences of email recipients within the Resend platform. Contacts are global entities identified by a UUID or an email address, which the system uses interchangeably in all subcommands. The system manages audience segmentation through Segments and fine-grained subscription preferences through Topics.

Sources: src/commands/contacts/index.ts:16-19, src/commands/contacts/utils.ts:60-73

Contact Management

Contacts store recipient data, including standard identification fields and custom metadata. Since the 2025 migration, contacts are global rather than audience-scoped.

Identification and Properties

The CLI identifies contacts using either a unique UUID or a literal email address. The utility function contactIdentifier parses the input string; if it contains an @ symbol, it treats the input as an email.

Contacts carry custom key-value properties. These properties are accessible in broadcast templates via triple-brace interpolation (e.g., {{{PROPERTY_NAME|fallback}}}). While firstName and lastName are standard options during creation, they are stored internally as FIRST_NAME and LAST_NAME properties.

Sources: src/commands/contacts/index.ts:16-24, src/commands/contacts/utils.ts:60-70

Subscription Status

A contact's global status is controlled by the --unsubscribed flag. This flag represents a team-wide opt-out from all broadcasts, overriding segment membership and topic preferences.

Sources: src/commands/contacts/index.ts:26-27, src/commands/contacts/create.ts:15-18

The diagram shows how the CLI determines whether to send an email or a UUID to the Resend API based on the presence of the @ symbol.

Audience Segmentation

Segments provide a mechanism to group contacts for targeted broadcasts. Contacts can belong to multiple segments simultaneously.

Membership Logic

You manage segment membership through specific contact subcommands:

• resend contacts add-segment: Associates a contact with a specific segment ID.
• resend contacts remove-segment: Disassociates a contact from a segment ID.
• resend contacts segments: Lists all segments currently associated with a specific contact.

Sources: src/commands/contacts/index.ts:29-32, skills/resend-cli/references/contacts.md:58-69

Command	Argument 1	Argument 2	Description
add-segment	Contact UUID/Email	--segment-id <id>	Adds contact to a segment
remove-segment	Contact UUID/Email	<segmentId>	Removes contact from segment
segments	Contact UUID/Email	N/A	Lists segments for contact

Sources: skills/resend-cli/references/contacts.md:58-69

Topic Subscriptions

Topics allow contacts to manage fine-grained preferences for different types of content (e.g., "Product Updates" vs. "Marketing").

Subscription States

Topic subscriptions support two explicit states:

1. opt_in: The contact explicitly agrees to receive broadcasts for this topic.
2. opt_out: The contact explicitly declines broadcasts for this topic.

If no specific subscription record exists for a contact, the system uses the topic's default_subscription setting.

Sources: src/commands/topics/index.ts:15-22, src/commands/contacts/utils.ts:80-86

The sequence diagram illustrates the flow of updating contact topic subscriptions, including the local JSON parsing step before the API call.

Sources: src/commands/contacts/update-topics.test.ts:50-70, src/commands/contacts/utils.ts:80-107

Bulk Operations (Imports)

The Resend CLI supports bulk-importing contacts via CSV files. This process is asynchronous.

CSV Import Architecture

When you initiate an import, the CLI uploads the CSV file as multipart/form-data. The API returns an import_id immediately, and the processing occurs in the background.

• Column Mapping: By default, the system matches columns case-sensitively to lowercase names (email, first_name, last_name). You must use the --column-map flag if your CSV headers use different formats (e.g., "Email Address").
• Conflict Strategy: The --on-conflict flag determines behavior for existing contacts. upsert (default) updates the existing record, while skip ignores the duplicate.
• Automatic Association: During import, contacts can be automatically added to segments or subscribed to topics using the --segment-id and --topics flags.

Sources: src/commands/contacts/imports/create.ts:53-122, skills/resend-cli/references/contacts.md:73-95

Import Technical Specifications

Parameter	Type	Constraint	Description
--file	Path	Max 100MB	Path to local CSV file
--column-map	JSON Object	N/A	Maps CSV headers to contact fields
--on-conflict	String	upsert | skip	Handling of existing contacts
--topics	JSON Array	[{id, subscription}]	Initial topic states for imports

Sources: src/commands/contacts/imports/create.ts:16-36, skills/resend-cli/references/contacts.md:73-86

Summary

Contacts & Audience Management provides the foundation for targeted email delivery. By combining global contact records with custom properties, segment-based grouping, and topic-based subscription preferences, the system enables precise audience targeting. The inclusion of bulk CSV imports with flexible column mapping ensures efficient management of large recipient lists while maintaining data integrity through conflict resolution strategies.

Sources: src/commands/contacts/index.ts:1-55, src/commands/contacts/imports/create.ts:40-50