Custom Contact Properties
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/contactproperties/ContactProperties.java
- src/main/java/com/resend/services/contactproperties/model/ContactProperty.java
- src/main/java/com/resend/services/contactproperties/model/CreateContactPropertyOptions.java
- src/main/java/com/resend/services/contactproperties/model/BaseContactProperty.java
- src/main/java/com/resend/services/contacts/model/CreateContactOptions.java
- src/main/java/com/resend/services/contacts/model/ContactImportPropertyMapping.java
- src/main/java/com/resend/services/contacts/model/ContactImportColumnMap.java
- src/main/java/com/resend/services/automations/model/ContactUpdateStepBuilder.java
Custom Contact Properties enable the extension of contact records with specialized metadata. The ContactProperties module manages the definition of these schema-level fields, while other modules like Contacts and ContactImports use them to store and process individual contact data. These properties support various data types, including strings, numbers, and booleans, and allow for fallback values during message personalization.
Sources: src/main/java/com/resend/services/contactproperties/ContactProperties.java, src/main/java/com/resend/services/contactproperties/model/ContactProperty.java:12-25
Property Management Service
The ContactProperties service handles interaction with the /contact-properties API endpoints. It provides standard CRUD (Create, Read, Update, Delete) operations to manage the custom schema.
Core Operations
The service executes network requests via the execute method inherited from BaseService. The table below describes the primary management functions:
| Operation | Method | API Endpoint | Description |
|---|---|---|---|
| Create | create(CreateContactPropertyOptions) | POST /contact-properties | Registers a new custom property key and type. |
| List | list() | GET /contact-properties | Retrieves all defined contact properties. |
| Get | get(String id) | GET /contact-properties/{id} | Fetches details for a specific property by ID. |
| Update | update(UpdateContactPropertyOptions) | PATCH /contact-properties/{id} | Modifies the fallback value of an existing property. |
| Remove | remove(String id) | DELETE /contact-properties/{id} | Deletes a property definition from the account. |
Sources: src/main/java/com/resend/services/contactproperties/ContactProperties.java:38-86
Service interaction flow
The diagram below illustrates how the ContactProperties service processes a creation request.
The sequence diagram shows the internal orchestration from the builder options to the final successful response object.
Sources: src/main/java/com/resend/services/contactproperties/ContactProperties.java:38-42
Data Models
Custom contact properties rely on several model classes to define the schema and handle responses.
ContactProperty Structure
The ContactProperty class represents a single property definition. It contains metadata such as the property key, the creation timestamp, and the expected data type.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the property definition. |
key | String | The string identifier used to reference the property in contacts. |
createdAt | String | Timestamp indicating when the property was created. |
type | String | The data type (e.g., "string", "number", "boolean"). |
fallbackValue | Object | The value used if a contact does not have this property set. |
Sources: src/main/java/com/resend/services/contactproperties/model/ContactProperty.java:12-25
Base Classes and Responses
Response models like CreateContactPropertyResponseSuccess and UpdateContactPropertyResponseSuccess inherit from BaseContactProperty. This base class encapsulates the common id and object fields returned by the Resend API.
Sources: src/main/java/com/resend/services/contactproperties/model/BaseContactProperty.java:8-12, src/main/java/com/resend/services/contactproperties/model/UpdateContactPropertyResponseSuccess.java:6-10
Property Association with Contacts
Individual contacts store values for custom properties within a Map<String, Object>.
Contact Creation and Updates
When you create or update a contact, you provide custom property values using the properties map. The CreateContactOptions.Builder and UpdateContactOptions.Builder provide a property(String key, Object value) method for adding single entries fluently.
CreateContactOptions options = CreateContactOptions.builder()
.email("user@example.com")
.property("tier", "premium")
.property("internal_id", 5501)
.build();
Sources: src/main/java/com/resend/services/contacts/model/CreateContactOptions.java:214-231, src/main/java/com/resend/services/contacts/model/UpdateContactOptions.java:217-234
Automations
Automations also support updating custom contact properties through the ContactUpdateStepBuilder. Users can set a full properties map or add individual properties to an automation step configuration.
Sources: src/main/java/com/resend/services/automations/model/ContactUpdateStepBuilder.java:68-90
Import Mappings
During CSV imports, custom properties must be mapped to specific columns in the source file.
Property Mapping Configuration
The ContactImportPropertyMapping class defines how a single custom property relates to a CSV column. It specifies the column name and the intended value type (defaults to "string").
Sources: src/main/java/com/resend/services/contacts/model/ContactImportPropertyMapping.java:15-22
Import Column Map
The ContactImportColumnMap contains a collection of these mappings. It allows the system to process non-standard columns during a batch import process.
This flowchart illustrates the transition of data from raw CSV columns to structured contact properties via the import mapping classes.
Sources: src/main/java/com/resend/services/contacts/model/ContactImportColumnMap.java:27-31, src/main/java/com/resend/services/contacts/model/ContactImportPropertyMapping.java:15-22
Summary
Custom Contact Properties provide a flexible schema management system within the Resend Java SDK. By defining properties through the ContactProperties service, you establish metadata fields that can be populated during contact creation, batch imports, or automated workflow steps. The system ensures data consistency through typed values and fallback mechanisms for personalized messaging.