Documentation / Guides

Domain Setup

6 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

5. MX record (optional)

MX lets MailingAPI receive email on this domain (inbound processing, MTA-side bounce handling). Skip this step if you only send from this domain.

Type: MX
Host: notifications.yourdomain.com
Priority: 10
Value: mx.outboxa.com

Note: If the domain already has an MX record (e.g. pointing to Google Workspace or Microsoft 365), don’t replace it — you’d receive your business mail inside MailingAPI instead of your real inbox. Use a dedicated sending subdomain (e.g. notifications.yourdomain.com) that has no conflicting MX.

6. Tracking CNAME and automatic SSL

The tracking CNAME switches the domain that tracking links (opens, clicks, unsubscribe) appear under from api.mailingapi.com to your own subdomain t.yourdomain.com. This materially improves deliverability — link domain and sender domain aligned under a single brand removes the “mismatch” signal used by spam filters (Gmail, Outlook, Mimecast).

Type: CNAME
Host: t.notifications.yourdomain.com
Value: api.mailingapi.com

The t. prefix is required — it’s the exact prefix MailingAPI injects into links in your emails, and it’s what routes traffic to our SSL infrastructure.

Automatic SSL certificate issuance

Once the CNAME verifies (usually <60 s after the DNS change), MailingAPI automatically provisions a free Let’s Encrypt certificate for t.yourdomain.com. Nothing to click, upload, or copy — no private keys cross your hands.

Flow:

  1. CNAME verification (you) — add the record, click “Verify”
  2. ACME HTTP-01 challenge (automated) — Let’s Encrypt challenges our infrastructure for proof of domain control; we respond
  3. Certificate issuance (automated) — cert lands in our encrypted store, ready for TLS handshake
  4. Runtime SNI loading — every request to https://t.yourdomain.com uses this cert

Typically <2 minutes from verification to active HTTPS. In the dashboard (Settings → Domains → [Your Domain]) you’ll see:

  • 🟡 Provisioning SSL certificate... — in progress (a few minutes max)
  • 🟢 SSL certificate active — done, links https://t.yourdomain.com/c/... work

Renewal

Let’s Encrypt certificates are valid for 90 days. MailingAPI renews them automatically every day (for any cert within 30 days of expiry). No action on your side — as long as the CNAME stays in place.

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)

HTTPS tracking still not working after a few minutes

If the dashboard shows Provisioning SSL certificate... for more than ~10 minutes:

  • Check CNAME propagation — dig t.yourdomain.com CNAME should return api.mailingapi.com. Some DNS registrars (especially cheap ones) take up to 48h to propagate.
  • CAA records — if you have a CAA record on your apex domain (yourdomain.com), make sure it includes 0 issue "letsencrypt.org" or remove it. CAA blocks Let’s Encrypt.
  • Let’s Encrypt rate limit — 50 certs per week per registered domain (eTLD+1). If you’ve exhausted the limit experimenting with subdomains, wait for the reset.
  • Contact support — if none of the above helps, our provisioning worker logs contain the exact ACME error.

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