Contacts API

Relevant source files

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

• contacts.go
• contact_imports.go
• contact_topics.go
• examples/contacts.go
• examples/global_contacts.go
• examples/contact_imports.go
• CHANGELOG.md

The Contacts API manages recipient data within the Resend platform. It provides methods to create, retrieve, update, and delete contacts, as well as specialized sub-services for bulk imports, segment memberships, and topic subscriptions.

This API supports two types of contacts: global contacts and audience-specific contacts. Global contacts exist at the account level and support custom properties, while audience-specific contacts are tied to legacy audience structures.

Sources: contacts.go:142-148, CHANGELOG.md:16-24

Core Contact Management

The ContactsSvc interface defines the primary operations for managing individual contact records. The implementation routes requests to either /contacts or /audiences/{id}/contacts depending on whether an AudienceId is provided.

Contact Structure

A contact record includes basic identity information and metadata.

Field	Type	Description
Id	string	Unique identifier for the contact
Email	string	Contact email address
FirstName	*string	First name of the contact
LastName	*string	Last name of the contact
Unsubscribed	bool	Subscription status flag
Properties	map	Custom key-value pairs (Global contacts only)

Sources: contacts.go:107-116, examples/global_contacts.go:50-58

Management Workflow

This diagram illustrates the logic for routing contact creation between global and legacy audience paths.

The SDK enforces that AudienceId cannot be used simultaneously with Segments or Topics during creation.
Sources: contacts.go:153-162, contacts.go:164-170

Contact Sub-Services

The ContactsSvcImpl struct aggregates several specialized sub-services to handle complex contact operations.

Service	Responsibility
Imports	Manages bulk CSV uploads of contact data
Topics	Manages contact-specific topic subscriptions (opt-in/opt-out)
Segments	Handles adding or removing contacts from segments
Properties	Defines the schema for custom metadata keys

Sources: contacts.go:21-27, CHANGELOG.md:25-30

Contact Topics

Contact topics allow granular control over what types of emails a recipient receives. Users can be updated via ID or Email.

Contact Imports

The Imports service handles bulk data ingestion via multipart CSV uploads.

• File Constraints: Maximum file size is 50MB.
• Conflict Resolution: Supports upsert (update existing) or skip strategies.
• Column Mapping: Maps CSV headers to contact fields like email, first_name, and properties.

Sources: contact_imports.go:44-59, examples/contact_imports.go:21-42

Data Operations

Retrieving Contacts

Contacts can be retrieved by their unique ID or their email address. When listing contacts, the SDK supports cursor-based pagination using Limit, After, and Before parameters.

// Get by ID or Email
options := &resend.GetContactOptions{
    Id: "hi@example.com", // Email address as identifier
}
contact, err := client.Contacts.Get(options)

Sources: contacts.go:230-240, examples/contacts.go:83-93

Custom Properties

Global contacts support a Properties map. Currently, the Resend API only accepts string values for these keys. Non-string values will trigger a validation error.

params := &resend.CreateContactRequest{
    Email: "user@example.com",
    Properties: map[string]any{
        "tier":   "premium",
        "active": "true", // Must be a string
    },
}

Sources: contacts.go:66-70, examples/global_contacts.go:50-58

Conclusion

The Contacts API provides a robust framework for managing recipient lifecycles. By transitioning to global contacts and utilizing the Segments and Topics sub-services, developers can implement sophisticated audience targeting and preference management within their Go applications.

Sources: CHANGELOG.md:5-15, contacts.go:14-27