Domain Management & DNS Verification
Relevant source files
The following files were used as context for generating this wiki page:
Domain Management in the Resend CLI provides a set of commands to provision, verify, and update domains for email operations. This system handles the technical handshake between the Resend platform and your DNS provider to authorize email sending and receiving.
The scope of this module includes creating domain identities, generating required DNS records (DKIM, SPF, MX), triggering asynchronous verification, and managing advanced tracking features like open and click tracking.
Sources: src/commands/domains/index.ts:1-10, skills/resend-cli/references/workflows.md:58-75
Domain Lifecycle
The CLI implements a multi-step workflow for establishing a verified sending domain. You must first create the domain entry to receive specific DNS records, apply those records to your DNS host, and then initiate the verification process.
The diagram above shows the standard sequence of operations required to move a domain from initial registration to a verified state.
Sources: src/commands/domains/index.ts:14-18, skills/resend-cli/references/workflows.md:58-75
Domain Creation
The create command registers a new domain and returns a list of DNS records. You can configure regional placement, TLS modes, and tracking subdomains during this phase.
| Parameter | Type | Description |
|---|---|---|
--name | string | The domain name (e.g., example.com). |
--region | choice | Physical region: us-east-1, eu-west-1, sa-east-1, ap-northeast-1. |
--tls | choice | Security mode: opportunistic (default) or enforced. |
--receiving | boolean | Enables inbound email processing (default: disabled). |
--tracking-subdomain | string | Custom subdomain for tracking (e.g., "track"). |
Sources: src/commands/domains/create.ts:11-30, skills/resend-cli/references/domains.md:16-29
DNS Record Management
When a domain is created or retrieved, the CLI provides a detailed table of records required for verification. These records establish trust via DKIM (DomainKeys Identified Mail) and handle routing via MX (Mail Exchanger) and SPF (Sender Policy Framework).
This sequence illustrates the interaction between the CLI, the API, and the external DNS infrastructure during the verification process.
Sources: src/commands/domains/create.ts:79-85, skills/resend-cli/references/domains.md:32-37
Verification Statuses
Domains progress through several states as the API attempts to validate the DNS configuration. You can check these statuses using the resend domains get <id> command.
| Status | Description |
|---|---|
not_started | Entry created but verification not yet triggered. |
pending | Verification triggered; API is checking DNS records. |
verified | DNS records matched; domain is ready for use. |
failed | Permanent failure in verification logic. |
temporary_failure | Transient issue preventing verification (e.g., DNS timeout). |
Sources: skills/resend-cli/references/domains.md:41-43, src/commands/doctor.ts:133-145
Advanced Domain Features
Domain Claiming
The claim system allows you to transfer a domain that is already verified in another Resend account to your own. This generates a unique TXT record that proves ownership before the transfer completes.
- Initialization:
resend domains claim create --name <domain>returns adomain_claimobject with a TXT record. - Verification:
resend domains claim verify <id>triggers the ownership check and transfer. - Result: The claimed domain receives fresh DKIM keys. You must update your DNS with these new records and run a standard domain verification after the claim completes.
Sources: skills/resend-cli/references/domains.md:78-98, tests/commands/domains/claim/create.test.ts:25-45
Monitoring and Health Checks
The resend doctor command provides a diagnostic overview of all domains associated with the active API key. It reports the count of verified versus pending domains and identifies if the API key has restricted "sending-only" permissions.
// Example of how Doctor validates domains
const domains = data?.data ?? [];
const verified = domains.filter((d) => d.status === 'verified');
const pending = domains.filter((d) => d.status !== 'verified');
if (domains.length === 0) {
return { name: 'Domains', status: 'warn', message: 'No domains configured' };
}
Sources: src/commands/doctor.ts:128-150
Conclusion
Domain Management and DNS Verification form the foundation of deliverability in the Resend CLI. By providing a structured workflow of creation, configuration, and asynchronous verification, the CLI ensures that domain identities are correctly established and secured before email operations begin. Users should utilize the doctor command regularly to monitor the health of these domain configurations.