Automated DNS Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Automated DNS Configuration is a core system within Send Again designed to streamline the technical setup required for high-volume email deliverability. To send emails through Amazon SES with high trust scores, a domain must have specific DNS records for verification, DKIM (DomainKeys Identified Mail), SPF (Sender Policy Framework), and DMARC.
This module automates the insertion and synchronization of these records across popular DNS providers including Cloudflare, Namecheap, and Amazon Route 53. By integrating directly with provider APIs, the system eliminates manual entry errors and ensures that the sending domain is correctly configured for SES.
Sources: README.md:12, src/app/api/workspaces/setup/route.ts:162-212
Architecture Overview
The DNS automation system follows a provider-based pattern where a central API route orchestrates calls to provider-specific libraries. The flow generally involves retrieving required SES tokens, identifying the correct DNS zone for a domain, and performing "upsert" operations to ensure records exist without creating duplicates.
The diagram above shows the data flow from the user interface through the backend setup route to the external DNS provider APIs.
Sources: src/app/api/workspaces/setup/route.ts:162-212, src/lib/cloudflare.ts:245-260
Supported DNS Records
The system manages a standard set of records required for Amazon SES deliverability. These records are generated based on tokens provided by AWS SES for a specific domain.
| Record Type | Purpose | Content Pattern |
|---|---|---|
| TXT | SES Domain Verification | _amazonses.example.com → [Verification Token] |
| TXT | SPF (Sender Policy Framework) | v=spf1 include:amazonses.com ~all |
| TXT | DMARC | _dmarc.example.com → v=DMARC1; p=quarantine; rua=mailto:dmarc@... |
| CNAME | DKIM (Identity 1-3) | [Token]._domainkey.example.com → [Token].dkim.amazonses.com |
Sources: src/lib/namecheap.ts:291-344, src/lib/cloudflare.ts:60-90
Provider Integrations
Cloudflare Integration
The Cloudflare implementation uses the apiToken to interact with the Cloudflare v4 API. It attempts to auto-detect the zoneId by checking domain candidates (e.g., sub.example.com -> example.com) if one is not explicitly provided.
- Key Logic: It uses different merge modes (
replace,additive,spf,dmarc) to handle existing records. For example, SPF and DMARC records look for existing values starting with those prefixes to perform a replacement rather than an addition. - API Path:
https://api.cloudflare.com/client/v4/zones/{zoneId}/dns_records
Sources: src/lib/cloudflare.ts:182-243, src/lib/cloudflare.ts:127-164
Namecheap Integration
Namecheap automation utilizes a specialized XML-based API. Unlike standard REST APIs, Namecheap requires the client to provide an apiUser, apiKey, and a whitelisted clientIp.
- Zone Resolution: The library splits the domain into SLD (Second Level Domain) and TLD (Top Level Domain) to identify the correct zone.
- Update Method: It uses
namecheap.domains.dns.setHostswhich requires submitting the entire list of host records for a domain at once. The library first fetches current records withgetHosts, merges the SES records, and sends the full set back.
Sources: src/lib/namecheap.ts:164-210, src/lib/namecheap.ts:346-371
Amazon Route 53 Integration
The Route 53 integration uses the @aws-sdk/client-route-53. It is designed to work within the same AWS environment as the SES instance.
- Record Upsert: Uses
ChangeResourceRecordSetsCommandwith theUPSERTaction. - Smart Merging: For TXT records (like SPF), it retrieves current values and intelligently merges the new SES requirements into the existing record set to avoid breaking other mail services.
Sources: src/lib/route53.ts:186-248, src/lib/route53.ts:140-163
Setup API Implementation
The backend logic for these operations is centralized in src/app/api/workspaces/setup/route.ts. This route handles both status checks (GET) and configuration actions (POST).
The sequence diagram illustrates the steps taken by the backend to fetch tokens and update a DNS provider.
Sources: src/app/api/workspaces/setup/route.ts:162-212
Configuration Parameters
The API expects different credential structures based on the provider chosen:
| Provider | Required Fields | Optional Fields |
|---|---|---|
| Namecheap | apiUser, username, apiKey, clientIp | useSandbox |
| Cloudflare | apiToken | zoneId |
| Route 53 | AWS Env Credentials | hostedZoneId |
Sources: src/app/api/workspaces/setup/route.ts:37-75
Conclusion
The Automated DNS Configuration system provides a robust abstraction layer over multiple DNS providers. By centralizing the logic for record generation and provider-specific API handling, it ensures that Send Again users can achieve high deliverability with minimal manual infrastructure management.
Sources: src/app/api/workspaces/setup/route.ts:117-151, README.md:12