Contacts & Properties Management
Relevant source files
The following files were used as context for generating this wiki page:
Contacts and Properties Management provides the infrastructure for maintaining recipient data and custom metadata. The system manages the lifecycle of individual contacts, their categorization into segments, their subscription to specific topics, and the definition of custom properties for advanced targeting.
This module differentiates between Global Contacts, which exist organization-wide and support custom properties, and Audience-specific Contacts, which belong to a specific audience container.
Contact Lifecycle Management
The resend.Contacts class manages contact entities. It routes requests based on the presence of an audience_id. If you provide an audience_id, the system performs operations within that audience; if you omit it, the system interacts with global contacts.
Architecture and Data Flow
The following diagram illustrates how the Contacts class determines the API endpoint based on the input parameters.
The logic differentiates pathing between global and audience-scoped resources.
Sources: resend/contacts/_contacts.py:164-184, examples/contacts_global.py:10-14
Core Operations
| Operation | Method | Description |
|---|---|---|
| Create | create() | Generates a new contact. Supports properties only for global contacts. |
| Update | update() | Modifies existing contact details. Requires id or email. |
| Get | get() | Retrieves a specific contact by ID or email. |
| List | list() | Fetches contacts. Supports pagination and filtering by segment_id. |
| Remove | remove() | Deletes a contact from the system. |
Sources: resend/contacts/_contacts.py:164-325
Contact Properties
Contact Properties define the schema for custom metadata attached to global contacts. You must define a property (key, type, and fallback) before assigning values to contacts. Supported types include string, number, and boolean.
Property Management Workflow
- Define Property: Use
resend.ContactProperties.create()to set the key and data type. - Assign Value: Pass the property key/value pair in the
propertiesdictionary during contact creation or update. - Fallback Logic: The system uses the
fallback_valuewhen a contact does not have a specific property value set.
Citing the flow of defining a schema before assigning data.
Sources: resend/contact_properties/_contact_properties.py:126-141, examples/contact_properties.py:10-18
Property Data Model
| Field | Type | Description |
|---|---|---|
key | str | The unique identifier for the property (e.g., "plan"). |
type | str | The data format: "string", "number", or "boolean". |
fallback_value | Any | Default value if the property is missing for a contact. |
Sources: resend/contact_properties/_contact_properties.py:104-123
Segments and Topics
The system organizes contacts through segments (logical groupings) and topics (subscription-based interests).
Segments
The ContactSegments class manages associations between contacts and segments. You can add or remove contacts from segments using either a contact_id or email.
- Add:
resend.Contacts.Segments.add(params) - List:
resend.Contacts.Segments.list(params) - Remove:
resend.Contacts.Segments.remove(params)
Sources: resend/contacts/segments/_contact_segments.py:145-212
Topics
Topics manage granular subscription statuses for contacts. Each topic association includes a subscription status: opt_in or opt_out.
- Update: Use
resend.Contacts.Topics.update()with a list of topic IDs and their new statuses. - List: Retrieve all topics associated with a contact via
resend.Contacts.Topics.list().
Sources: resend/contacts/_topics.py:108-164, examples/contacts.py:84-118
Implementation Example: Global Contact with Properties
Global contacts allow the attachment of arbitrary metadata defined via Contact Properties.
# Create a global contact with properties
create_params: resend.Contacts.CreateParams = {
"email": "global.user@example.com",
"first_name": "Global",
"properties": {
"tier": "premium",
"role": "admin",
},
}
contact = resend.Contacts.create(create_params)
Sources: examples/contacts_global.py:20-33
Summary
Contacts & Properties Management provides a dual-layered approach to recipient handling. While Audience-specific contacts offer simple containment, Global contacts integrated with Contact Properties enable complex metadata schemas. The inclusion of Topics and Segments ensures that applications can manage both logical groupings and explicit user subscription preferences across synchronous and asynchronous execution environments.
Sources: resend/contacts/_contacts.py:12-25, resend/contacts/segments/_contact_segments.py:18-35