Domains Management

Relevant source files

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

• domains.go
• domain_claims.go
• examples/domains.go
• examples/domain_claims.go
• domains_test.go
• examples/with_pagination.go

Domains Management allows you to configure and verify sender identities within the Resend platform. This module handles the registration of domain names, DNS record generation for SPF, DKIM, and tracking, and the process of claiming domains previously verified by other accounts.

Sources: domains.go:10-40, domain_claims.go:12-40

Domain Lifecycle and Verification

The system manages domains through a series of states starting from creation to full verification. When you create a domain, the API generates specific DNS records that you must add to your DNS provider to prove ownership and authorize email sending.

Domain States

Domains transition through several statuses during the verification process:

Status	Description
pending	Verification is in progress.
verified	Domain is fully authenticated and ready for use.
failed	Verification failed due to incorrect or missing DNS records.
not_started	The domain is registered but no verification attempt has occurred.
partially_verified	Some records (e.g., DKIM) are verified while others are pending.
partially_failed	One or more required records failed verification.

Sources: domains.go:30-37, domains_test.go:300-340

Verification Flow

The following diagram illustrates the lifecycle of a domain from registration to verification.

The user initiates verification after updating their DNS provider with the records returned by the creation or get endpoints.
Sources: domains.go:193-214, examples/domains.go:21-85

Core Data Structures

CreateDomainRequest

This structure defines the parameters used to register a new domain.

Field	Type	Description
Name	string	The domain name (e.g., "example.com").
Region	string	The physical AWS region for sending (e.g., "us-east-1").
CustomReturnPath	string	Subdomain for the return path.
TrackingSubdomain	string	Subdomain used for open and click tracking.
OpenTracking	*bool	Enables tracking of email opens.
ClickTracking	*bool	Enables tracking of link clicks.
Capabilities	struct	Defines if the domain is for sending, receiving, or both.

Sources: domains.go:87-95, examples/domains.go:24-34

Domain Capabilities

Capabilities manage the functional status of a domain. Statuses can be enabled or disabled.
Sources: domains.go:76-85

type DomainCapabilities struct {
    Sending   DomainCapabilityStatus `json:"sending,omitempty"`
    Receiving DomainCapabilityStatus `json:"receiving,omitempty"`
}

Sources: domains.go:82-85

Domain Claims

Domain claims allow an account to take ownership of a domain that was previously verified by another Resend account. This process requires a specific TXT record to prove current ownership.

Claim Process Flow

The sequence below shows the interaction between the Client and the Domain Claims service.

Claim Blocked Reasons

A claim may be blocked for several reasons defined by the API:

• grace_period: The domain was recently released.
• recent_owner_activity: The current owner is actively using the domain.
• pending_scheduled_emails: There are emails queued for delivery under the current owner.

Sources: domain_claims.go:23-29

DNS Records Management

The Record struct represents individual DNS entries required for domain authentication.

Field	Type	Description
Record	RecordType	Category: SPF, DKIM, Tracking, or TrackingCAA.
Type	string	DNS type: MX, TXT, CNAME, or CAA.
Value	string	The actual value to be placed in the DNS record.
Status	string	Verification status of this specific record.

Sources: domains.go:20-28, domains.go:153-161

Implementation Details

Updating Domains

The UpdateDomainRequest supports partial updates. Because Go's omitempty tag excludes false values for booleans, the SDK provides explicit setter methods to ensure false values are sent to the API.

func (r *UpdateDomainRequest) SetOpenTracking(val bool) {
	r.OpenTracking = val
	r.openTrackingSet = true
}

func (r *UpdateDomainRequest) SetClickTracking(val bool) {
	r.ClickTracking = val
	r.clickTrackingSet = true
}

Sources: domains.go:121-131, domains_test.go:240-272

Pagination

Listing domains supports limit-based pagination. You can provide a ListOptions struct to control the result set size and navigation.

limit := 5
domainsResp, err := client.Domains.ListWithOptions(ctx, &resend.ListOptions{
    Limit: &limit,
})

Sources: examples/with_pagination.go:24-30, domains.go:217-233

Summary

Domains Management provides a structured interface for domain authentication and ownership transfers. By utilizing the DomainsSvc and DomainClaimsSvc interfaces, you can automate the lifecycle of sender identities, monitor DNS verification statuses, and configure tracking capabilities for your outbound email traffic.
Sources: domains.go:41-55, domain_claims.go:65-72