Contact Properties
Relevant source files
The following files were used as context for generating this wiki page:
- src/contact-properties/contact-properties.ts
- src/contact-properties/interfaces/contact-property.ts
- src/contact-properties/interfaces/create-contact-property-options.interface.ts
- src/common/utils/parse-contact-properties-to-api-options.ts
- src/contact-properties/contact-properties.spec.ts
- src/contacts/contacts.ts
Contact Properties define custom metadata fields that you associate with contacts in Resend. They enable you to store specific data types like strings or numbers for each subscriber, which you can later use for personalization or segmentation.
The ContactProperties class manages these definitions by providing methods to create, list, retrieve, update, and delete property schemas.
Sources: src/contact-properties/contact-properties.ts
Architecture and Data Flow
The module acts as a wrapper for the /contact-properties API endpoints. It transforms SDK-specific camelCase interfaces into the snake_case formats required by the Resend API.
Property Transformation Flow
This diagram shows how data moves from the SDK method call to the API request.
The parseContactPropertyToApiOptions utility ensures that fields like fallbackValue are correctly mapped to fallback_value for the API.
Sources: src/common/utils/parse-contact-properties-to-api-options.ts:1-32
Data Structures
Contact Properties support two primary data types: string and number. Each property requires a unique key and an optional fallbackValue.
Contact Property Object
| Field | Type | Description |
|---|---|---|
id | string | The unique identifier for the property definition. |
key | string | The machine-readable name used to reference the property. |
type | 'string' | 'number' | The data type allowed for this property. |
fallbackValue | string | number | null | The default value used if a contact lacks this property. |
createdAt | string | Timestamp of when the property was defined. |
Sources: src/contact-properties/interfaces/contact-property.ts:1-32
Interface Relationships
This diagram represents the relationship between property definitions and their API representations.
Core Methods
Create a Property
You define new property schemas by calling the create method.
- Provide a
key(e.g., "country"). - Specify a
type("string" or "number"). - Optionally provide a
fallbackValue.
Sources: src/contact-properties/contact-properties.ts:33-43, src/contact-properties/contact-properties.spec.ts:31-41
List Properties
The list method retrieves all defined contact properties. The SDK automatically parses the paginated response to return formatted ContactProperty objects.
Sources: src/contact-properties/contact-properties.ts:45-74
Update a Property
You can modify the fallbackValue of an existing property.
- You must provide the property
idin the payload. - Only the
fallbackValueis typically updated; thekeyandtyperemain immutable.
Sources: src/contact-properties/contact-properties.ts:114-138, src/contact-properties/contact-properties.spec.ts:182-198
Integration with Contacts
Once a property is defined in the ContactProperties module, it can be populated for individual contacts through the Contacts module.
When creating or updating a contact, the properties field accepts an object where keys match the defined property keys and values match the defined types.
Sources: src/contacts/contacts.ts:60-75, src/contacts/contacts.ts:145-155
Error Handling
Methods validate required fields before making API calls. If an id is missing in get, update, or remove requests, the SDK returns a missing_required_field error without attempting a network request.
| Error Name | Cause |
|---|---|
missing_required_field | Occurs when id or key is not provided. |
not_found | Occurs when the requested property ID does not exist. |
Sources: src/contact-properties/contact-properties.ts:79-88, src/contact-properties/contact-properties.spec.ts:152-167
Summary
Contact Properties provide a structured schema for custom contact data. By defining keys and types through the ContactProperties class, you ensure data consistency across your audience. The system handles the conversion between developer-friendly camelCase and API-required snake_case automatically.