Step-by-step guide to verifying your domain with DNS records for email sending and receiving.

DNS Verification

This guide walks you through verifying your domain by configuring the required DNS records.

Overview

DNS verification proves domain ownership and enables email functionality. The process involves:

Registering your domain in the API
Adding DNS records to your domain's DNS configuration
Waiting for DNS propagation (typically 1-60 minutes)
Triggering verification check

Required DNS Records

When you register a domain, the API provides specific DNS records to add to your domain registrar or DNS provider.

MX Records (Receiving Email)

MX records tell mail servers where to deliver emails for your domain.

Type: MX
Name: @ (or yourdomain.com)
Value: 10 inbound-smtp.us-east-1.amazonaws.com
Priority: 10
TTL: 300

TXT Records (Verification & Authentication)

TXT records are used for domain verification and email authentication.

Domain Verification Token

Type: TXT
Name: _amazonses.yourdomain.com
Value: [token-provided-by-api]
TTL: 300

SPF Record (Sender Policy Framework)

Type: TXT
Name: @ (or yourdomain.com)
Value: v=spf1 include:amazonses.com ~all
TTL: 300

DKIM Record (DomainKeys Identified Mail)

Type: TXT
Name: [selector]._domainkey.yourdomain.com
Value: v=DKIM1; k=rsa; p=[public-key-from-api]
TTL: 300

DMARC Record (Optional but Recommended)

Type: TXT
Name: _dmarc.yourdomain.com
Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com
TTL: 300

Step-by-Step Verification

Step 1: Register Your Domain

POST /api/email/domains
Content-Type: application/json

{
  "domain": "yourcompany.com"
}

Response:

{
  "id": "dom_987654321",
  "domain": "yourcompany.com",
  "status": "pending",
  "dnsRecords": [
    {
      "type": "MX",
      "name": "yourcompany.com",
      "value": "10 inbound-smtp.us-east-1.amazonaws.com",
      "priority": 10
    },
    {
      "type": "TXT",
      "name": "_amazonses.yourcompany.com",
      "value": "ABC123xyz789...token..."
    },
    {
      "type": "TXT",
      "name": "selector1._domainkey.yourcompany.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqG..."
    }
  ]
}

Step 2: Add DNS Records

Example: Cloudflare

Log in to Cloudflare Dashboard
Select your domain
Go to DNS > Records
Click Add Record for each required record
Set TTL to Auto or 300 (5 minutes)

Example: AWS Route53

# Create hosted zone if needed
aws route53 create-hosted-zone --name yourcompany.com

# Add MX record
aws route53 change-resource-record-sets \
  --hosted-zone-id Z123456789 \
  --change-batch file://mx-record.json

# Add TXT records
aws route53 change-resource-record-sets \
  --hosted-zone-id Z123456789 \
  --change-batch file://txt-records.json

Step 3: Check DNS Propagation

Use these tools to verify DNS propagation:

# Check MX records
dig MX yourcompany.com

# Check TXT records
dig TXT _amazonses.yourcompany.com
dig TXT yourcompany.com

# Online tool
# https://whatsmydns.net

Step 4: Trigger Verification

Once DNS records have propagated, trigger verification:

POST /api/email/domains/dom_987654321/verify

Response:

{
  "id": "dom_987654321",
  "domain": "yourcompany.com",
  "status": "active",
  "verificationStatus": {
    "mx": true,
    "dkim": true,
    "spf": true,
    "dmarc": false
  },
  "verifiedAt": "2024-01-15T11:30:00Z"
}

Verification Status Check

Check the current verification status:

GET /api/email/domains/dom_987654321

Response:

{
  "id": "dom_987654321",
  "domain": "yourcompany.com",
  "status": "pending",
  "verificationStatus": {
    "mx": false,
    "dkim": false,
    "spf": false,
    "dmarc": null
  },
  "dnsRecords": [
    {
      "type": "MX",
      "name": "yourcompany.com",
      "value": "10 inbound-smtp.us-east-1.amazonaws.com",
      "verified": false,
      "lastChecked": "2024-01-15T10:05:00Z"
    }
  ]
}

Troubleshooting

Verification Fails

Common issues and solutions:

Issue	Solution
DNS not propagated	Wait 5-60 minutes and retry
Wrong record value	Copy exact value from API response
Extra whitespace	Ensure no spaces at start/end of values
Multiple SPF records	Combine into single record: `v=spf1 include:amazonses.com include:_spf.google.com ~all`

Check DNS Records

# MX record check
dig +short MX yourcompany.com

# Expected output:
# 10 inbound-smtp.us-east-1.amazonaws.com.

# TXT record check
dig +short TXT _amazonses.yourcompany.com

# Expected output:
# "ABC123xyz789...token..."

Retry Verification

async function verifyWithRetry(domainId: string, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(`/api/email/domains/${domainId}/verify`, {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });
    
    const result = await response.json();
    
    if (result.status === 'active') {
      console.log('Domain verified!');
      return result;
    }
    
    console.log(`Attempt ${i + 1} failed, waiting 60 seconds...`);
    await new Promise(r => setTimeout(r, 60000));
  }
  
  throw new Error('Verification failed after max retries');
}

Webhook Events

Domain verification triggers webhook events:

Event	Description
`domain.verified`	Domain successfully verified
`domain.verification_failed`	Verification attempt failed

Code Example: Complete Verification Flow

async function registerAndVerifyDomain(domain: string) {
  // 1. Register domain
  const registerRes = await fetch('/api/email/domains', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain })
  });
  
  const { id, dnsRecords } = await registerRes.json();
  
  // 2. Display DNS instructions
  console.log('Add these DNS records to your domain:');
  dnsRecords.forEach(r => {
    console.log(`\n${r.type} Record:`);
    console.log(`  Name: ${r.name}`);
    console.log(`  Value: ${r.value}`);
    if (r.priority) console.log(`  Priority: ${r.priority}`);
  });
  
  // 3. Wait for user to add records
  console.log('\nPress Enter when DNS records are added...');
  await waitForEnter();
  
  // 4. Verify with retries
  return verifyWithRetry(id);
}

// Helper function
function waitForEnter(): Promise<void> {
  return new Promise(resolve => {
    process.stdin.once('data', () => resolve());
  });
}

DNS Provider Guides

Cloudflare

Log in to Cloudflare Dashboard
Select your domain
Go to DNS > Records
Add records with:
- Proxy status: DNS only (gray cloud)
- TTL: Auto

GoDaddy

Log in to GoDaddy
Go to My Products > DNS
Click Add for each record type
Save changes

Namecheap

Log in to Namecheap
Go to Domain List > Manage
Go to Advanced DNS
Add records under Host Records

AWS Route53

Use the AWS CLI or Console to add records to your hosted zone.

Domain Management - Domain CRUD operations
Inboxes - Create inboxes on verified domains
Troubleshooting - Common issues and solutions

DNS Verification

On this page