Contacts API

Relevant source files

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

• src/contacts.rs
• src/segments.rs
• src/topics.rs
• src/events.rs
• src/emails.rs
• CHANGELOG.md

The Contacts API provides a service to manage individual recipients within the Resend ecosystem. It allows you to create, retrieve, update, and delete contacts, as well as manage their association with audiences, segments, and topics.

The API serves as the primary interface for building and maintaining subscriber lists. It integrates with custom properties for data enrichment and supports bulk operations through contact imports.

Sources: src/contacts.rs:32-34, src/contacts.rs:253-268

Contact Management

The ContactsSvc struct implements methods to interact with contact resources. You identify contacts using either a unique ContactId or their email address.

Core Operations

• Create: Generates a new contact record. You can specify an audience_id to place the contact in a specific audience, otherwise the contact is created at the global level.
• Retrieve: Fetches a Contact object containing the email, names, subscription status, and custom properties.
• Update: Modifies existing contact details using ContactChanges.
• Delete: Removes a contact from the system.

Sources: src/contacts.rs:35-86, src/contacts.rs:271-294

Data Structure: Contact

Field	Type	Description
id	ContactId	Unique identifier for the contact.
email	String	Email address of the recipient.
first_name	Option<String>	Optional first name.
last_name	Option<String>	Optional last name.
unsubscribed	bool	Current subscription status.
properties	Option<HashMap>	Custom metadata associated with the contact.

Sources: src/contacts.rs:358-372, CHANGELOG.md:89-91

Custom Properties

Custom properties allow you to store additional metadata for contacts, such as "company_name" or "plan_type". You must define a property schema before assigning values to contacts.

The following flowchart shows the lifecycle of a custom property:

The diagram represents the management flow for ContactProperty definitions.
Sources: src/contacts.rs:179-245, src/contacts.rs:521-558

Property Types

Properties support two data types:

• String
• Number

Sources: src/contacts.rs:521-526

Segments and Topics

Contacts interact with organizational structures called Segments and Topics to manage grouping and subscription preferences.

Segments

Segments group contacts based on specific criteria. You can add contacts to segments during creation or via dedicated add/remove methods. The SegmentsSvc manages the segments themselves, while ContactsSvc handles the membership.
Sources: src/segments.rs:16-95, src/contacts.rs:141-177

Topics

Topics manage specific subscription categories (e.g., "Weekly Newsletter"). Contacts can be opted in or out of specific topics.
Sources: src/topics.rs:17-64, src/contacts.rs:105-139

Relationship Diagram

This diagram illustrates the relationship between a contact and its associated groupings and metadata.
Sources: src/contacts.rs:253-268, src/segments.rs:135-144, src/topics.rs:98-106

Contact Imports

The Import API allows for bulk creation of contacts by uploading CSV files. You must provide a ContactImportColumnMap to define how CSV columns map to contact fields like email, first_name, and custom properties.

The sequence shows the process of initiating a bulk contact import via the create_import method.
Sources: src/contacts.rs:253-339, src/contacts.rs:693-705

Import Conflict Handling

When importing, you can specify an on_conflict strategy:

• Upsert: Update existing contacts or create new ones.
• Skip: Ignore the record if the contact already exists.

Sources: src/contacts.rs:684-688

Event Integration

Contact activities trigger webhook events. These events allow external systems to react to changes in the contact database.

Event Type	Logic
contact.created	Triggers when a new contact is added.
contact.updated	Triggers when contact details or properties change.
contact.deleted	Triggers when a contact is removed.
contact.topics.updated	Triggers when a contact's topic subscription status changes.

Sources: src/events.rs:219-226, src/events.rs:228-232, CHANGELOG.md:16-18

The Contacts API serves as a foundation for personalized communication by maintaining rich recipient profiles and their subscription preferences within segments and topics.