Domain Management & Claims
Relevant source files
The following files were used as context for generating this wiki page:
Domain Management & Claims handles the lifecycle of sender domains within the Resend platform. This system allows users to register domains, configure tracking settings, and verify ownership via DNS records. When a domain is already associated with another team, the Claims system provides a workflow to prove ownership and transition the domain.
The IResend interface defines the primary contract for these operations, while the Domain and DomainClaim classes represent the core data entities.
Domain Entities
The Domain object represents a registered DNS domain used for sending and receiving emails. It contains configuration for delivery regions, tracking capabilities, and required DNS validation records.
Domain Properties
| Field | Type | Description |
|---|---|---|
Id | Guid | Unique identifier for the domain. |
Name | string | The DNS name of the domain. |
Status | DomainStatus | Validation state (e.g., NotStarted, Verified, PartiallyVerified). |
Region | DeliveryRegion | AWS region used for email delivery (e.g., us-east-1). |
OpenTracking | bool? | Indicates if email opens are tracked. |
ClickTracking | bool? | Indicates if links within emails are tracked. |
Records | List<DomainRecord> | DNS records (SPF, DKIM, etc.) required for validation. |
Sources: src/Resend/Domain.cs:8-66, tests/Resend.Tests/DomainTests.cs:84-118
Domain Lifecycle
The following diagram illustrates the flow from domain creation through verification.
The domain status changes based on the successful verification of required DNS records like SPF and DKIM.
Sources: tools/Resend.ApiServer/Controllers/DomainController.cs:22-48, tests/Resend.Tests/DomainTests.cs:124-162
Domain Claims
Domain Claims are utilized when a user attempts to add a domain that is already verified by a different Resend team. In this scenario, Resend creates a placeholder domain and issues a specific TXT record that the user must add to their DNS to prove ownership.
Claim Data Model
A DomainClaim contains the status of the claim and the specific DNS record required to resolve the ownership conflict.
| Property | Type | Description |
|---|---|---|
Id | Guid | Unique identifier for the claim request. |
DomainId | Guid? | Identifier of the placeholder domain created for the claim. |
Status | DomainClaimStatus | Current state of the claim (e.g., Pending, Blocked, Verified). |
Record | DomainClaimRecord | The TXT record name and value required for DNS verification. |
BlockedReason | string? | Reason for block (e.g., grace_period, recent_owner_activity). |
Sources: src/Resend/DomainClaim.cs:11-82, tests/Resend.Tests/DomainClaimTests.cs:51-86
Claim Verification Process
The claiming process follows a specific sequence of API calls and external DNS updates.
The user must add the TXT record to their DNS provider before triggering the DomainClaimVerifyAsync method.
Sources: src/Resend/IResend.cs:238-278, tools/Resend.ApiServer/Controllers/DomainController.cs:134-192
API Operations
The IResend interface provides comprehensive methods for managing domains and claims.
Domain Methods
DomainListAsync(): Retrieves all domains for the authenticated user.DomainAddAsync(DomainAddData): Creates a new sender domain.DomainRetrieveAsync(Guid): Gets details for a specific domain.DomainUpdateAsync(Guid, DomainUpdateData): Updates tracking and configuration.DomainVerifyAsync(Guid): Triggers an asynchronous DNS check for domain validation.DomainDeleteAsync(Guid): Removes a domain from the team.
Claim Methods
DomainClaimAsync(string, DeliveryRegion?): Initiates a claim for an existing domain.DomainClaimRetrieveAsync(Guid): Checks the current status of a claim using the placeholder domain ID.DomainClaimVerifyAsync(Guid): Requests the API to verify the ownership TXT record.
Sources: src/Resend/IResend.cs:169-280, tools/Resend.ApiServer/Controllers/DomainController.cs:18-131
Configuration and Tracking
When adding or updating a domain, users can configure specific behaviors such as click and open tracking.
var data = new DomainAddData()
{
DomainName = "example.com",
TlsMode = TlsMode.Enforced,
Capabilities = new DomainCapabilities()
{
Sending = "enabled",
Receiving = "disabled",
},
ClickTracking = true,
TrackingSubdomain = "links"
};
Setting TrackingSubdomain creates a CNAME record in the domain's Records list to handle tracking redirects.
Sources: tests/Resend.Tests/DomainTests.cs:13-33, src/Resend/Domain.cs:52-58
Summary
The Domain Management & Claims system provides the infrastructure for identity verification in Resend. Through the Domain and DomainClaim entities, the SDK handles standard domain registration and the specialized ownership transfer process required when domains are shared or moved between teams. Complete verification depends on the successful resolution of DNS records provided by the API during the creation or claim phases.