Documentation / Guides

Domain Setup

3 min read

Before sending emails in production, you need to verify your domain. This proves you own the domain and allows email servers to trust your messages.

Why domain verification matters

Without verification:

  • Emails may land in spam
  • Some providers reject messages entirely
  • You can’t use your own branding
  • Deliverability is unpredictable

With verification:

  • SPF, DKIM, DMARC authenticate your emails
  • Higher inbox placement rates
  • Professional sender reputation
  • Full control over your email identity

Adding a domain

Via Dashboard

  1. Go to Settings → Domains
  2. Click Add domain
  3. Enter your domain (e.g., notifications.yourdomain.com)
  4. Click Add

Via API

curl -X POST https://api.mailingapi.com/v1/domains \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "notifications.yourdomain.com"}'

Response:

{
  "id": "dom_abc123",
  "domain": "notifications.yourdomain.com",
  "status": "pending",
  "dns_records": [...]
}

Choosing your domain

Use a subdomain

We recommend using a subdomain rather than your root domain:

✓ mail.yourdomain.com
✓ notifications.yourdomain.com
✓ alerts.yourdomain.com
✗ yourdomain.com (not recommended)

Why?

  • Isolates email reputation from your website
  • Easier to manage DNS records
  • Separate domains for transactional vs. marketing

Naming conventions

Use case Example
Transactional emails mail.yourdomain.com
Notifications notifications.yourdomain.com
Alerts alerts.yourdomain.com
Marketing (separate) news.yourdomain.com

DNS records

After adding a domain, you’ll receive DNS records to configure:

1. SPF Record

SPF tells email servers which IPs can send email from your domain.

Type: TXT
Host: notifications.yourdomain.com
Value: v=spf1 include:spf.mailingapi.com ~all

If you already have an SPF record, add our include:

v=spf1 include:_spf.google.com include:spf.mailingapi.com ~all

Important: You can only have one SPF record per domain.

2. DKIM Record

DKIM signs your emails cryptographically, proving they weren’t tampered with.

Type: CNAME
Host: mlapi._domainkey.notifications.yourdomain.com
Value: mlapi._domainkey.mailingapi.com

We manage key rotation automatically when you use CNAME.

3. DMARC Record

DMARC tells receivers what to do with emails that fail SPF/DKIM.

Type: TXT
Host: _dmarc.notifications.yourdomain.com
Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com

DMARC policies:

  • p=none — Monitor only, no action
  • p=quarantine — Send failures to spam
  • p=reject — Reject failures entirely

Start with p=none, then tighten after confirming everything works.

4. Ownership verification

A TXT record proving you control this domain:

Type: TXT
Host: _mailingapi.notifications.yourdomain.com
Value: mailingapi-verify=abc123xyz

Getting DNS records

Via Dashboard

Go to Settings → Domains → [Your Domain] → DNS Records

Via API

curl https://api.mailingapi.com/v1/domains/dom_abc123/dns-records \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "records": [
    {
      "type": "TXT",
      "host": "notifications.yourdomain.com",
      "value": "v=spf1 include:spf.mailingapi.com ~all",
      "purpose": "spf"
    },
    {
      "type": "CNAME",
      "host": "mlapi._domainkey.notifications.yourdomain.com",
      "value": "mlapi._domainkey.mailingapi.com",
      "purpose": "dkim"
    }
  ]
}

Adding records to your DNS

The process varies by provider. Here are common ones:

Cloudflare

  1. Go to DNS settings
  2. Click Add record
  3. Select record type (TXT or CNAME)
  4. Enter name and value
  5. Save (proxy OFF for email records)

AWS Route 53

  1. Go to Hosted zones → Your domain
  2. Click Create record
  3. Enter record details
  4. Click Create records

GoDaddy

  1. Go to DNS Management
  2. Click Add
  3. Select record type
  4. Enter host and value
  5. Save

Note: DNS changes can take up to 48 hours to propagate, though usually it’s much faster.

Verifying your domain

After adding DNS records:

Via Dashboard

  1. Go to Settings → Domains → [Your Domain]
  2. Click Verify
  3. Wait for verification (usually seconds to minutes)

Via API

curl -X POST https://api.mailingapi.com/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "status": "verified",
  "spf": {"status": "valid"},
  "dkim": {"status": "valid"},
  "dmarc": {"status": "valid"},
  "ownership": {"status": "valid"}
}

Verification statuses

Status Meaning
pending DNS records not yet checked
verifying Verification in progress
verified All records valid, ready to send
failed One or more records invalid

If verification fails, check the response for specific errors:

{
  "status": "failed",
  "spf": {"status": "valid"},
  "dkim": {"status": "missing", "error": "CNAME record not found"},
  "dmarc": {"status": "valid"},
  "ownership": {"status": "valid"}
}

Troubleshooting

“SPF record not found”

  • Verify the TXT record exists at the correct host
  • Check for typos in the value
  • Wait for DNS propagation

“Too many DNS lookups”

SPF has a limit of 10 DNS lookups. If you’re over:

  • Remove unused includes
  • Use IP addresses directly for static servers
  • Consider SPF flattening

“DKIM signature mismatch”

  • Ensure CNAME points to exactly mlapi._domainkey.mailingapi.com
  • Check the host is mlapi._domainkey.yourdomain.com
  • Remove any trailing dots

“DMARC not aligned”

  • Ensure SPF and DKIM domains match your From address
  • Check DMARC policy allows subdomains (sp= tag)

Multiple domains

You can add multiple domains to your account:

curl -X POST https://api.mailingapi.com/v1/domains \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"domain": "alerts.yourdomain.com"}'

Each domain:

  • Requires separate verification
  • Gets its own API keys
  • Has independent reputation

Use cases:

  • Different products/brands
  • Separate transactional from marketing
  • Regional domains

Best practices

  1. Use subdomains — Don’t risk your root domain reputation
  2. Start with monitoring DMARC — Use p=none initially
  3. Check records regularly — DNS can change or expire
  4. Monitor deliverability — Use our dashboard analytics
  5. Separate email types — Different domains for different purposes

Next steps