Audiences and Contacts
Relevant source files
The following files were used as context for generating this wiki page:
Audiences and Contacts provide the structural foundation for managing communication recipients within the Resend ecosystem. Audiences serve as high-level containers that group related individuals, while Contacts represent the specific entities within those groups, each maintaining unique identifiers, metadata, and subscription preferences.
The system facilitates bulk operations through imports, granular categorization via segments, and preference management through topics. Developers interact with these resources through dedicated service classes that handle CRUD operations and specialized sub-resource management.
Architecture and Data Relationships
The architecture follows a hierarchical structure where Audiences encapsulate Contacts. Each Contact can be further associated with specific Segments for filtering and Topics for subscription management. Custom metadata is handled via Contact Properties.
The diagram illustrates the relationships between core entities, highlighting how Contacts act as the central node for preferences and metadata.
Sources: tests/Service/Audience.php, tests/Service/Contact.php, src/Contacts/Topic.php
Audience Management
Audiences act as the primary grouping mechanism. The Audience service allows for creating, retrieving, listing, and deleting these containers.
Key Operations
- Create: Initializes a new audience with a specific name.
- Get: Retrieves details for a specific audience using its unique ID.
- List: Returns a collection of all audiences associated with the account.
- Remove: Deletes an audience resource.
Sources: tests/Service/Audience.php:5-39
Contact Operations
Contacts are the individual recipients stored within Resend. The Contact service supports operations using both unique IDs and email addresses as identifiers.
Lifecycle Management
The service provides methods to manage the contact lifecycle:
- Creation: Adds a new contact, typically requiring an email address.
- Retrieval: Fetches contact details by ID or email.
- Updating: Modifies contact attributes such as
first_name. - Removal: Deletes the contact record by ID or email.
| Method | Identifier | Endpoint Pattern |
|---|---|---|
get | ID or Email | GET /contacts/{id_or_email} |
create | Data Array | POST /contacts |
update | ID or Email | PATCH /contacts/{id_or_email} |
remove | ID or Email | DELETE /contacts/{id_or_email} |
Sources: tests/Service/Contact.php:5-82
Contact Sub-resources
Contacts interact with three primary sub-services: Topics, Segments, and Imports.
Subscription Topics
Topics define the subscription status (opt_in or opt_out) for specific types of communication.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the topic. |
name | string | Display name of the topic. |
subscription | string | Preference: opt_in or opt_out. |
Sources: src/Contacts/Topic.php:10-15, tests/Service/Contacts/Topic.php:5-42
Segmentation
Segments allow for logical grouping of contacts. The system enables adding contacts to segments, listing a contact's segment memberships, and removing them.
Flow of contact interaction with segments through the Service layer.
Bulk Imports
Imports allow for the creation of multiple contacts using external files (e.g., CSV). The process involves uploading a file resource to the contacts/imports endpoint.
Sources: tests/Service/Contacts/Import.php:5-26
Contact Properties
Contact Properties define custom metadata fields applicable to contacts. They support different data types and display names for administrative organization.
Field Definitions
| Property | Description |
|---|---|
key | The internal identifier (e.g., company_name). |
type | The data format (e.g., string). |
display_name | The human-readable label for the property. |
Sources: tests/Service/ContactProperty.php:5-52
Summary
The Audiences and Contacts modules provide a robust framework for recipient management. By leveraging Audiences for grouping, Contacts for individual data, and sub-resources like Segments and Topics for granular control, the system ensures organized and compliant communication flows. Bulk operations via Imports and custom metadata via Properties further extend the system's flexibility for diverse integration requirements.