Domains & Claims Management

Relevant source files

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

• src/domains/domains.ts
• src/domains/claims/domain-claims.spec.ts
• src/domains/domains.spec.ts
• src/domains/interfaces/domain.ts
• src/common/utils/parse-domain-to-api-options.spec.ts
• src/request-options.spec.ts

Domains & Claims Management handles the lifecycle of email sending domains and the verification of domain ownership through claims. This system allows you to register domains, configure tracking settings, manage regional deployments, and verify DNS records required for email delivery.

The module provides a structured interface for interacting with the Resend API to ensure domains are correctly configured for sending and receiving capabilities. It also manages "Claims," which are temporary objects used to initiate and track the verification process for a specific domain.

Sources: src/domains/domains.ts, src/domains/interfaces/domain.ts

Domain Lifecycle Management

The Domains class provides methods to manage the full lifecycle of a domain. You can create new domains, retrieve their details, list all domains associated with an account, update configurations, and remove them when no longer needed.

Core Domain Operations

The system interacts with the /domains API endpoints to perform CRUD operations.

This diagram shows the mapping between SDK methods in the Domains class and the corresponding REST API endpoints.
Sources: src/domains/domains.ts:25-103

Domain Configuration Parameters

When creating or updating a domain, you can configure various technical parameters:

Parameter	Type	Description
name	string	The domain name (e.g., example.com).
region	DomainRegion	AWS region for deployment (e.g., us-east-1, eu-west-1).
customReturnPath	string	Custom subdomain for SPF/Return-Path records.
openTracking	boolean	Enables or disables email open tracking.
clickTracking	boolean	Enables or disables email click tracking.
trackingSubdomain	string	Custom subdomain for tracking links.
capabilities	object	Defines if the domain supports sending or receiving.

Sources: src/domains/interfaces/domain.ts:98-107, src/domains/domains.spec.ts:167-170, src/common/utils/parse-domain-to-api-options.spec.ts:19-23

Domain Claims

Domain Claims represent the process of asserting ownership over a domain. A claim provides the specific DNS records (usually TXT) that you must add to your DNS provider to prove control.

Claim Workflow

1. Initiate: You create a claim for a domain name and region.
2. Verify DNS: The API returns a verification record (e.g., resend-domain-verification=...).
3. Trigger Verification: You call the verify method once the DNS record is propagated.

The sequence shows how a user moves from initiating a claim to triggering the verification check via the API.
Sources: src/domains/claims/domain-claims.spec.ts:38-111, src/request-options.spec.ts:98-100

Claim Data Structure

A successfull claim response includes the verification record and the current status of the claim.

Field	Type	Description
id	string	Unique identifier for the domain claim.
status	string	Status of the claim (e.g., pending).
record	object	Contains type, name, value, and ttl for the DNS record.
domain_id	string	The ID of the domain associated with the claim.
expires_at	string	Timestamp when the claim verification window expires.

Sources: src/domains/claims/domain-claims.spec.ts:15-30

Domain Status and Records

Domains can exist in various states depending on the verification progress of their underlying DNS records (SPF, DKIM, etc.).

Domain Status Types

A domain's overall health is determined by its status field:

• not_started: Initial state after creation.
• pending: Verification is in progress.
• verified: All required records are correctly configured.
• failed: Verification failed.
• partially_verified: Some records (like DKIM) are verified, but others (like Tracking) are not.
• partially_failed: At least one required record has failed verification.

Sources: src/domains/interfaces/domain.ts:31-37, src/domains/domains.spec.ts:515-568

Technical Records

The DomainRecords interface defines several types of records provided by the API for DNS configuration:

Record Type	Description
SPF	Sender Policy Framework records for authorization.
DKIM	DomainKeys Identified Mail records for cryptographic signing.
Receiving	MX records required for inbound email processing.
Tracking	CNAME records used for custom tracking subdomains.
TrackingCAA	CAA records for certificate authority authorization on tracking links.

Sources: src/domains/interfaces/domain.ts:39-96

Implementation Details

The Domains class uses a private resend client to execute HTTP requests. It also initializes a DomainClaims sub-resource during construction.

// Example implementation of domain creation
async create(
  payload: CreateDomainOptions,
  requestOptions: CreateDomainRequestOptions = {},
): Promise<CreateDomainResponse> {
  const data = await this.resend.post<CreateDomainResponseSuccess>(
    '/domains',
    parseDomainToApiOptions(payload),
    requestOptions,
  );
  return data;
}

Sources: src/domains/domains.ts:44-53

Request Options Support

All domain and claim methods support optional RequestOptions, allowing users to pass custom headers or an AbortSignal for request cancellation.
Sources: src/request-options.spec.ts:91-100

Summary

Domains & Claims Management provides the foundation for secure and deliverable email sending. By managing domain objects and their associated claims, the system ensures that DNS verification (SPF/DKIM) is completed and that advanced features like custom tracking and regional routing are correctly applied to the outgoing mail flow.