Contact Properties & Topics

Relevant source files

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

• contact_properties.go
• contact_topics.go
• contacts.go
• examples/contact_properties.go
• examples/global_contacts.go
• CHANGELOG.md
• contact_properties_test.go
• contact_topics_test.go

Contact Properties and Contact Topics are specialized sub-services within the Resend Go SDK designed to manage metadata and subscription preferences for global contacts. Introduced in version 3.0.0, these services allow developers to define custom schema-based fields (Properties) and manage granular email category interests (Topics) for individual users.

These modules work in conjunction with the main Contacts service. Contact Properties provide the schema definitions required before custom data can be attached to a global contact, while Contact Topics handle the opt-in/opt-out status of a contact regarding specific communication categories.

Sources: CHANGELOG.md:3-33, contacts.go:21-27

Contact Properties

The ContactPropertiesSvc manages the definitions of custom metadata fields that can be attached to contacts. These definitions ensure that data stored in a contact's Properties map adheres to a specific data type and provides a fallback value when the property is not explicitly set for a contact.

Data Architecture

Contact properties are defined at the project level. A contact property definition includes a unique key, a data type (e.g., "string" or "number"), and a fallback value.

Key Property Attributes

Attribute	Type	Description
Key	String	The unique identifier for the property (e.g., "age", "tier").
Type	String	The data type for the property. Supported types include string and number.
FallbackValue	Any	The value returned if a contact does not have this property defined.

Sources: contact_properties.go:35-41, examples/contact_properties.go:19-35

Implementation Details

The ContactPropertiesSvcImpl provides methods to perform standard CRUD operations on property definitions.

1. Creation: Validates that Key and Type are present before sending a POST request to /contact-properties.
2. Retrieval: Fetches all properties via List or a specific definition by ID.
3. Updating: Only the FallbackValue can be updated for an existing property.
4. Removal: Permanently deletes a property definition.

Sources: contact_properties.go:66-177

Contact Topics

The ContactTopicsSvc manages the relationship between a contact and specific communication topics. This service enables granular preference management, allowing contacts to be subscribed (opt_in) or unsubscribed (opt_out) from specific categories of emails.

Subscription Flow

Subscriptions are managed per contact. The system identifies contacts using either their unique Id or their Email address.

Topic Subscription Data Models

Structure	Field	Description
ContactTopic	Subscription	The status for the contact: "opt_in" or "opt_out".
TopicSubscriptionUpdate	Id	The ID of the Topic being updated.
UpdateContactTopicsRequest	Topics	A slice of TopicSubscriptionUpdate objects for batch updates.

Sources: contact_topics.go:9-33

Retrieving and Updating Subscriptions

The service allows listing all topics a contact is associated with and their current subscription status. Updates are performed as a PATCH operation, where the request body consists of an array of topic IDs and their new subscription states.

// Example: Updating topic subscriptions for a contact
updateTopicsParams := &resend.UpdateContactTopicsRequest{
    Id: contact.Id,
    Topics: []resend.TopicSubscriptionUpdate{
        {
            Id:           topic.Id,
            Subscription: "opt_in",
        },
    },
}
updatedTopics, err := client.Contacts.Topics.UpdateWithContext(ctx, updateTopicsParams)

Sources: examples/contacts.go:114-128, contact_topics.go:88-118

Integration with Global Contacts

Contact Properties and Topics are primary features of "Global Contacts"—contacts that do not require an AudienceId.

Relationship Schema

Atomic Operations

When creating a global contact, the SDK supports adding segments and topics in a single request. However, custom Properties values must refer to Keys that have already been created via the ContactProperties service.

• Note: Currently, the Resend API primarily accepts string values for properties during contact creation and update. Non-string values may trigger validation errors if the property definition type does not match.

Sources: contacts.go:66-83, examples/global_contacts.go:19-54

Summary

The Contact Properties & Topics modules provide the infrastructure for advanced contact segmentation and preference management. Contact Properties allow for schema-defined metadata (strings and numbers) on global contacts, while Contact Topics provide a mechanism for managing granular opt-in/opt-out preferences. Both services are accessible via the main Client.Contacts interface as sub-services (Client.Contacts.Properties and Client.Contacts.Topics).

Sources: contacts.go:21-27, CHANGELOG.md:28-33