​

Troubleshooting: email DNS verification drift and recovery

​

Where you see the drift

• Email dashboard — the DNS status widget shows one traffic-light chip per record type (SPF, DKIM, DMARC) for the platform-default domain and your custom domain, updated about once a minute. Green means the record resolves to the expected value; yellow is a partial or inconclusive verdict; red is a confirmed failure.
• Send path — a send through a regressed domain fails with a provider 403: “domain is not verified.” The Delivery Log row stays on your side of the provider handoff.
• Bell notification — when the daily re-check or an interactive re-check sees a previously-green record flip to a confirmed failure, the platform writes the regression to the domain’s history and raises a notification. A resolver blip (SERVFAIL, timeout) never fires the bell — only confirmed failures become regressions.

​

Step 1 — Read the traffic light

curl "https://orbit.devotel.io/api/v1/email/domains/${domain}/dns-status" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

• data.overallStatus is the worst of the per-record verdicts: valid (green, all records pass), warning (yellow, partial or inconclusive), invalid (red, at least one confirmed failure), or unknown (not checked yet).
• data.records[] carries one entry per record with kind (spf / dkim / dmarc, plus mx and bimi where configured), status, the DNS value the platform saw (recordActual), and the value it expected (recordExpected) — compare the two to find the drift.
• For DKIM, each selector appears as its own entry with a selector field; a single failing selector turns the whole domain red.
• data.providerSendability (present when the provider was consulted on this read) tells you whether the email provider actually considers the domain registered. An all-green DNS grid with a “not registered” provider verdict still 403s — that case is Step 3 below.
• Pass ?refresh=true to force a live re-check instead of the cached verdict; the interactive Verify DNS / Re-check now action in the dashboard uses the same flag and also pokes the provider to re-verify.

​

Diagnose per record

• Yellow with an empty actual value usually means DNS has not propagated yet. A newly published record caches at the resolver for its TTL; wait it out and re-poll rather than re-editing.
• A status that flips red for minutes then recovers on its own is a resolver blip, not drift — those verdicts are deliberately excluded from the regression bell and history trend, and need no action.

​

Step 2 — Check the history before you edit

1. When did it regress? The first red snapshot after a green stretch lines up with a zone edit on your side — match the timestamp against your registrar change log before you revert the wrong record.
2. Did it recover? After a fix, this log is how you confirm the verdict flipped back once the TTL expired; a green live status with a still-red recent history means the fix published but the cached verdict has not rolled yet.

​

Step 3 — Re-verify on demand

curl -X POST "https://orbit.devotel.io/api/v1/settings/channels/email/verify-dns" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.example.com"}'

​

Step 4 — Watch the warm-up posture while the domain is down

• Any dedicated-IP warm-up loses its anchor — the ramp is anchored to the first recorded send, and suppressed sends do not advance it. Read GET /api/v1/email/warmup-status after the regression clears: it tells you today’s recommended cap, how much headroom is left today, and whether the reputation feedback loop is holding your ceiling down.
• If you queued a campaign into a regressed domain, those rows sat in the queue rather than bouncing — drain them after re-verification instead of re-sending duplicates (see message stuck in queued for the queue-side diagnosis).

​

Step 5 — Resume sending

1. GET /api/v1/email/domains/:domainId/dns-status returns overallStatus: "valid" with no red or yellow record.
2. providerSendability on the same response reports the domain as registered with the provider (or the interactive verify already ran end-to-end).
3. GET /api/v1/email/domains/:domainId/dns-history shows the recent snapshots green past the record TTL.

​

Recovery checklist

1. Read dns-status for the domain; note which kind is red or yellow.
2. Match recordActual against recordExpected for that record; the mismatch is the drift.
3. Check dns-history for the regression timestamp; line it up with your registrar change log.
4. Fix the record at your registrar (single SPF, full DKIM p= key, DMARC policy in place, Return-Path CNAME intact).
5. Run POST /api/v1/settings/channels/email/verify-dns (or the dashboard Verify DNS button) and confirm the provider verdict.
6. Re-poll dns-status; confirm green, then confirm dns-history rolled past the TTL window.
7. Check warmup-status before resuming volume past the day’s cap.
8. Resume queued congestion control (not bulk re-sends — drain the queue).

​

When to escalate

• The DNS zone publicly resolves the exact expected value (dig TXT <name> matches recordExpected), yet dns-status keeps reporting yellow or red past a full TTL cycle.
• providerSendability still reports “not registered” after an interactive verify on an all-green grid.
• Every record reads unknown — that points at the platform’s check path, not your zone.

• Your tenant ID (Settings → Organization in the dashboard; also returned as organizationId by GET /api/v1/me).
• The sending domain affected.
• The record kind and the expected/actual values the dns-status response returned for the failing record.
• The timestamp of the first red snapshot from dns-history.

​

See also

• Email channel guide — domain setup, the verification lifecycle, and webhook events
• Email bounces and spam complaints — the recipient-side failure class that survives a green DNS grid
• Message stuck in queued — drain queued email rows without re-sending duplicates
• Email endpoints reference — request and response shapes for dns-status, dns-history, and warmup-status