DNS Doctor — the DNS, DMARC, SPF and DKIM skill

DNS Doctor looks up and verifies DNS records, checks propagation and registration, and diagnoses email authentication and DNS health. It returns observed evidence and copy-paste fix records generated by a validating engine, never an LLM guess. Explain the result and relay records exactly as returned; do not author a DNS record yourself.

Choose the shortest workflow for the user's request

Ask for a missing domain, exact record name or type before calling a tool. Use this router first; the full scan workflow below is for a broad diagnosis, not a prerequisite for every lookup. Stop when the requested question is answered. Two jobs have their own short skills: verify-change (did my change land, has it propagated, look again after the TTL) and fix-dmarc (scan, the next DMARC record, re-check).

Do not require a full scan, account connection or monitoring setup for a public record lookup. Show relevant returned report, signup and dashboard URLs as clickable links using the actual unchanged URL; a description alone is not a link. Keep website access available when setup continues in chat.

What this skill sends, and where

Every tool call goes to one host, https://dnsdoctor.dev (or the local @dnsdoctor/mcp client, which calls the same public API). What leaves the machine is exactly what the user asked to check: a domain name, and for the focused tools a record name, an IP address, a DKIM selector, a pasted DMARC record, or an uploaded DMARC report. Nothing else is read or sent — no files, no environment variables, no credentials, no message contents.

The email test is the one case where the USER sends something: one email of their choosing, from their own mail system, to the single-use address start_email_test returns. DNS Doctor keeps only the verdicts and selected header facts (no body, no attachments) for 24 hours (90 days for a test started with an account). One AI read by an AI language-model provider sees a redacted view of the message: the subject and the first 600 characters of the text with addresses, links, long numbers and token-like strings masked, the sender headers with the part before every @ masked, our own authentication results, and the sending domain's age and DNS facts. It is not given the message's recipients (To, Cc or the envelope), though a name in the subject or text can remain. The read costs at most 0.5 of the score and is what the inbox estimate is made from. The domain names in the message's links are looked up for their registration date and checked against a malware list; no link is ever visited.

Two things the user should know before you scan a domain for them:

• A scan result is a public report page at https://dnsdoctor.dev/scan/<domain> (the free scanner is a public service, like a DNS lookup site). Do not scan a domain the user wants kept private, and say so if they ask.
• Account tools sign in through the host. The three monitoring reads (get_alerts, get_readiness, get_lookalikes), list_email_tests, list_my_domains and the dnsdoctor://domains resource need the user's DNS Doctor account: the host's own sign-in (OAuth to dnsdoctor.dev) connects it when one of them is called. Never read a credential from the user's machine, and never ask the user to paste one into the chat.

DNS Doctor never changes DNS: it returns records for a human to publish.

When to use this skill

Reach for it whenever a user describes any of:

• looking up a DNS record or verifying a record they just published
• comparing propagation across regions, or checking registration/expiry
• "our email is going to spam" / "customers aren't getting our mail"
• "SPF PermError" or "too many DNS lookups" (the SPF 10-lookup limit)
• "DMARC is stuck at p=none" / "how do I get to p=reject safely"
• a bounce code like 550 5.7.515, 550 5.7.1, or dmarc=fail
• "is my domain blacklisted?" / "am I on a blocklist?"
• "when does my domain / TLS certificate expire?"
• "who can send as us?" / auditing SPF includes before or after an email provider migration
• locking down parked, redirect or brand-defensive domains that send no mail
• "is my mail actually DKIM-signed?" / "test an email from Google Workspace, Microsoft 365, Mailchimp or our app"
• "how do we get our logo next to our mail in Gmail / Yahoo / Apple Mail?" / "why doesn't our BIMI logo show?"

Connect to the server

The tools come from the DNS Doctor MCP server. Two ways to reach it:

• Streamable HTTP (default, no setup): https://dnsdoctor.dev/mcp — anonymous access exposes all the scanner tools. This plugin's MCP configuration already points here.
• Local stdio: npx -y @dnsdoctor/mcp@1.20.0 — the same 29 tools, run as a local process that calls the public DNS Doctor REST API. Use it when your client prefers stdio, or when you want the server under your own supervision. Its README explains account access for the monitoring reads.

The diagnosis tools need no token and are enough for a one-off diagnosis. An API token (Authorization: Bearer dnsd_…) additionally unlocks:

• get_alerts, get_readiness and get_lookalikes — the three monitoring reads, which return one account's own data. They are listed for everyone and callable with a token: they appear in the tool list whether or not you have one. A linked account can authorize these reads through the host connection; otherwise a valid API token is required.
• list_email_tests — the account's own earlier email tests, under the same token rule.
• list_my_domains — every domain on the account with its state and next step, under the same token rule.
• watch_record_change — one free record watch for a linked account: it reads the record once and, on wait or edit, emails the account once when the change is finished (up to 48 hours). Asking again returns the running watch.
• the dnsdoctor://domains resource — the account's continuously-monitored domains. Over HTTP that resource is likewise always listed and refused without a token.

You cannot create a token, so do not try. Minting is session-authenticated: the account owner creates one while signed in, at /dashboard/settings on the DNS Doctor site. A refusal tells you the exact page — relay that link to the person you are helping and let them decide whether they want one. Never ask anyone to paste a token, or any other credential, to you.

Tools

The whole-domain and enrollment tools — start here for any "is this domain's email set up correctly" question:

Twelve focused tools for the single questions a full scan over-answers. Each runs the same validating engine:

Two tools test a real message — the evidence a DNS scan cannot give (a published DKIM key does not prove the sender signs with it) — and a third lists the account's earlier tests:

Four reads over an account's own continuously-monitored domains. All four need a linked account or API token (see Connect to the server), all four are read-only by decision, and all four answer from the same cores the dashboard reads, so an agent and its human are never told different things:

An anonymous or invalid-token call to any of them is refused with the page the owner mints a token on. Relay that page; do not retry around the refusal, and do not ask anyone for a credential.

Every domain input is normalized server-side; a malformed domain returns a clean tool error, never a crash. A temperror-shaped tool error means a DNS lookup timed out — retry, never report it as a verdict. A domain the token's account does not verifiably own returns the same "not found" as a domain that does not exist — that is deliberate, and not something to probe around.

Full scan workflow — for a broad diagnosis

1. Scan. Call scan_domain (fresh) or get_report (accept a recent cached report). Each check returns a status: pass, warn, fail, info, or temperror.
2. Read the verdicts failing-first. Surface fail then warn then the rest.
   • temperror is transient, NOT a failure — it means a DNS/network lookup timed out. Say "couldn't be resolved right now", never "your SPF is broken".
   • info is an honest "not found / not applicable" (e.g. no DKIM selector among the ones we probed, or a redacted RDAP expiry) — never report it as a failure.
   • Check not_registered before anything else. When the report carries not_registered: true, the domain has no DNS records at all — it is not registered, or it has no nameservers. No check ran, so every status is an info placeholder and zero failing checks does not mean the domain is healthy. Say the domain does not resolve (a typo is the usual cause), propose no SPF/DKIM/DMARC records for it — there is no zone to publish them in — and don't offer monitoring until it resolves. The report's next_steps summary says all of this; relay it.
   • Read the DMARC check's details, not just its status. One of them can say the domain's aggregate reports are going to a third party that has not published the RFC 7489 §7.1 authorization record — meaning the reports are being silently discarded and the owner is collecting nothing, while the DMARC record itself still looks correct. It is reported as a detail rather than a failure because the domain's own configuration is not at fault; relay it anyway, since a DMARC rollout waiting on evidence that never arrives is a stall with no visible cause.
3. Explain the findings in plain language: what is wrong, why it lets mail be spoofed or land in spam, and what fixing it achieves (see "Explain it for a non-expert" below).
4. Get the fix record. For DMARC, follow the fix-dmarc skill: build_dmarc_upgrade derives the step server-side (a scan tops out at p=quarantine; p=reject comes only from the readiness engine; never pct). When record is null, relay the rationale as the answer and never compose a record to fill the gap. policy describes the returned record and is null with it; the domain's observed policy is in current_policy.
5. Present the record verbatim (see the rule below) and tell the human to publish it in their DNS host.
6. The human applies it; then verify. DNS Doctor never writes DNS. Follow the verify-change skill: check_record with the published value as expected_value (on wait, wait check_again_after_seconds; on edit, relay found_at), check_propagation for regional coverage, then scan_domain to confirm the verdict flipped.

Explain it for a non-expert

The person asking is usually a small-business owner or someone who built their site with an AI tool, not a sysadmin. Talk to them that way:

• After each finding, add ONE plain sentence on what it means for their email: who could send mail pretending to be them, whether their mail may land in spam or be refused, or what would stop working.
• Gloss a technical word the first time you use it, in 3-6 words: SPF (the list of servers allowed to send your mail), DKIM (a signature that proves the mail is really yours), DMARC (what to do with mail that fails those checks), MX (where your incoming mail is delivered), reverse DNS or PTR (the name a mail server's address points back to), BIMI (your logo next to your mail).
• At most one fact per reply, taken only from the heading below that matches the finding you are explaining, and only when it helps them understand their own result. Never state a fact, number or date that is not in the tool results or under that heading.
• Don't lecture and don't scare. No history of email, no worst-case stories: a missing record is something to fix, not an emergency. The record and the next step stay the main part of the reply.

Facts you may use

Pick a fact only from the heading for the finding you are explaining, and use at most one per reply. Quote it as written or shorter and never add a number it does not state. Each fact names its source in the comment after it. "Our numbers" are DNS Doctor's own scans: aggregates only, the domains we last checked in October 2026 that have email set up (they publish MX records). Where the DNS Doctor result card is shown it may carry its own short tip from this list, so add no fact of your own there.

No DMARC record (No DMARC record found)

• DMARC is how you tell mail providers what to do with mail that fakes your address.<!-- source: RFC 7489 §6.3, https://www.rfc-editor.org/rfc/rfc7489.html#section-6.3 -->
• Gmail requires DMARC from anyone sending more than 5,000 messages a day to Gmail; p=none is enough.<!-- source: Google, 2024, https://support.google.com/a/answer/81126 -->
• Yahoo has required DMARC (at least p=none) from bulk senders since February 2024.<!-- source: Yahoo, 2024, https://senders.yahooinc.com/best-practices/ -->
• Since May 5, 2025, Outlook.com refuses mail from domains sending over 5,000 a day without SPF, DKIM and DMARC.<!-- source: Microsoft, 2025, https://techcommunity.microsoft.com/blog/microsoftdefenderforoffice365blog/strengthening-email-ecosystem-outlook%E2%80%99s-new-requirements-for-high%E2%80%90volume-senders/4399730 -->
• When Outlook.com refuses a bulk sender for missing SPF, DKIM or DMARC, the bounce reads "550 5.7.515 Access denied".<!-- source: Microsoft, 2025, https://techcommunity.microsoft.com/blog/microsoftdefenderforoffice365blog/strengthening-email-ecosystem-outlook%E2%80%99s-new-requirements-for-high%E2%80%90volume-senders/4399730 -->
• Phishing and spoofing was the crime most often reported to the FBI in 2025: 191,561 complaints.<!-- source: FBI IC3 2025 Annual Report, https://www.ic3.gov/AnnualReport/Reports/2025_IC3Report.pdf -->
• Our numbers: of the 483 domains with email that DNS Doctor last checked in October 2026, 28% had no DMARC record.<!-- source: DNS Doctor scans, October 2026, scripts/skill_stats.sql (dmarc_none_found_pct) -->
• Only about half (52.1%) of the world's 1.8 million busiest websites had a DMARC record in early 2026.<!-- source: EasyDMARC 2026 DMARC Adoption Report (top 1.8M domains), https://easydmarc.com/blog/easydmarc-releases-2026-dmarc-adoption-report/ -->
• Since April 2025, GoDaddy adds a DMARC record set to p=quarantine to every domain newly bought or transferred there.<!-- source: GoDaddy, 2025 (checked 2026-11), https://www.godaddy.com/resources/skills/enhancing-domain-security-dmarc-implementation -->

DMARC at p=none (DMARC is published but p=none)

• p=none only asks for reports; it does not ask providers to block fake mail.<!-- source: RFC 7489 §6.3, https://www.rfc-editor.org/rfc/rfc7489.html#section-6.3 -->
• Providers that send DMARC reports send them about once a day by default.<!-- source: RFC 7489 §6.3 (ri default 86400 seconds), https://www.rfc-editor.org/rfc/rfc7489.html#section-6.3 -->
• Each report counts the mail sent as your domain and whether it passed SPF and DKIM.<!-- source: RFC 7489 §7.2, https://www.rfc-editor.org/rfc/rfc7489.html#section-7.2 -->
• Our numbers: of 483 domains with email we checked in October 2026, 35% were at p=none.<!-- source: DNS Doctor scans, October 2026, scripts/skill_stats.sql (dmarc_p_none_pct) -->
• Of the top million websites that publish DMARC, fewer than half (46.9%) ask providers to block or junk fake mail.<!-- source: Internet Society Pulse, Tranco top 1M, July 2026, https://pulse.internetsociety.org/en/blog/two-providers-a-stubborn-plateau-and-a-very-long-tail-email-in-the-tranco-top-1m/ -->
• 95% of Fortune 500 companies publish DMARC, and more than 80% of them have moved past p=none.<!-- source: EasyDMARC 2026 DMARC Adoption Report, https://easydmarc.com/blog/easydmarc-releases-2026-dmarc-adoption-report/ -->

DMARC without a rua= address (no reports requested)

• Without a rua= address, mailboxes have nowhere to send their daily reports, so you cannot see who sends as you.<!-- source: RFC 7489 §6.3 (rua, ri default 86400 seconds), https://www.rfc-editor.org/rfc/rfc7489.html#section-6.3 -->

Two DMARC records (Multiple DMARC records found)

• With two DMARC records, providers apply neither, as if you had none.<!-- source: RFC 7489 §6.6.3, https://www.rfc-editor.org/rfc/rfc7489.html#section-6.6.3 -->

DMARC at p=quarantine or p=reject (why keep reading the reports)

• p=quarantine asks providers to treat failing mail as suspicious, often the spam folder.<!-- source: RFC 7489 §6.3, https://www.rfc-editor.org/rfc/rfc7489.html#section-6.3 -->
• p=reject asks providers to refuse failing mail outright.<!-- source: RFC 7489 §6.3, https://www.rfc-editor.org/rfc/rfc7489.html#section-6.3 -->
• A new sending service can fail DMARC until it signs or sends mail aligned with your domain.<!-- source: RFC 7489 §3.1 (alignment), https://www.rfc-editor.org/rfc/rfc7489.html#section-3.1 -->
• Forwarded mail and mailing lists can fail DMARC even when the mail is really yours.<!-- source: RFC 7960 §1 and §2.2, https://www.rfc-editor.org/rfc/rfc7960.html -->
• DMARC reports are worth reading after enforcing: a new or broken sender shows up there first.<!-- source: RFC 7489 §7.2 (reports carry per-source SPF/DKIM results), https://www.rfc-editor.org/rfc/rfc7489.html#section-7.2 -->
• Our numbers: of 483 domains with email we checked in October 2026, 36% were at p=quarantine or p=reject (21.5% and 14.5%).<!-- source: DNS Doctor scans, October 2026, scripts/skill_stats.sql (dmarc_quarantine_pct, dmarc_reject_pct) -->
• Among the 5,000 largest US organisations, 38.4% of domains are at p=reject and 22% at p=quarantine.<!-- source: Red Sift US DMARC adoption report, March-June 2026, https://findthephish.redsift.com/blog/us-dmarc-adoption-report -->

No SPF record (No SPF record found)

• Since February 2024, Gmail requires SPF or DKIM from every sender.<!-- source: Google, 2024, https://support.google.com/a/answer/81126 -->
• Bulk senders to Yahoo need both SPF and DKIM.<!-- source: Yahoo, 2024, https://senders.yahooinc.com/best-practices/ -->
• Our numbers: of 483 domains with email we checked in October 2026, 7.5% had no SPF record.<!-- source: DNS Doctor scans, October 2026, scripts/skill_stats.sql (spf_missing_pct) -->

Two SPF records (SPF record is invalid because a second record exists)

• A domain may have only one SPF record; with two, the SPF check returns an error (permerror).<!-- source: RFC 7208 §4.5, https://www.rfc-editor.org/rfc/rfc7208.html#section-4.5 -->

SPF over or near 10 lookups (SPF exceeds the 10 DNS-lookup limit, SPF is near the 10-lookup limit)

• SPF allows 10 DNS lookups. Past that, receivers treat the whole record as broken, even for your real senders.<!-- source: RFC 7208 §4.6.4, https://www.rfc-editor.org/rfc/rfc7208.html#section-4.6.4 -->
• The limit counts the whole chain: the includes inside your includes count too.<!-- source: RFC 7208 §4.6.4 ("during SPF evaluation"), https://www.rfc-editor.org/rfc/rfc7208.html#section-4.6.4 -->

SPF ends in ~all (observation only: SPF is diagnose-only, never propose changing it)

• Our numbers: of the SPF records we found in October 2026 on domains with email, 53% end in ~all.<!-- source: DNS Doctor scans, October 2026, scripts/skill_stats.sql (spf_softfail_pct_of_found) -->

DKIM not found (DKIM: checked common selectors, none found)

• The scan tries common selector names only, so a key under another name can still exist.<!-- source: DNS Doctor's DKIM check, its own title ("checked common selectors") -->
• Bulk senders to Yahoo and Outlook.com need DKIM, not just SPF.<!-- source: Yahoo 2024, https://senders.yahooinc.com/best-practices/ ; Microsoft 2025, https://techcommunity.microsoft.com/blog/microsoftdefenderforoffice365blog/strengthening-email-ecosystem-outlook%E2%80%99s-new-requirements-for-high%E2%80%90volume-senders/4399730 -->
• DKIM usually survives forwarding when the message is unchanged; SPF often does not.<!-- source: RFC 7960 §2.2 and §3.2.1, https://www.rfc-editor.org/rfc/rfc7960.html -->

DKIM key of 1024 bits (uses a weak 1024-bit key)

• 1024-bit DKIM keys still work; 2048 bits is recommended where your email provider offers it.<!-- source: RFC 8301 §3.2 (MUST at least 1024, SHOULD 2048), https://www.rfc-editor.org/rfc/rfc8301.html#section-3.2 -->
• Our numbers: of the DKIM keys we found in October 2026 on domains with email, 28% were 1024-bit.<!-- source: DNS Doctor scans, October 2026, scripts/skill_stats.sql (dkim_1024_pct_of_found) -->

DKIM found (check_dkim_selector: the selector is published)

• DKIM signs each message so mailboxes can tell it was not changed on the way. Each sending service uses its own key.<!-- source: RFC 6376 §1, https://www.rfc-editor.org/rfc/rfc6376.html#section-1 -->

No MX records (No MX records)

• With no MX record, senders try your domain's own address instead, usually the website server.<!-- source: RFC 5321 §5.1 (implicit MX), https://www.rfc-editor.org/rfc/rfc5321.html#section-5.1 -->
• A domain that takes no mail can say so with a "null MX" record.<!-- source: RFC 7505, https://www.rfc-editor.org/rfc/rfc7505.html -->

Own mail server (check_reverse_dns: ptr_missing, mismatch)

• Gmail requires a sending server's address to have matching forward and reverse DNS (a PTR record).<!-- source: Google, 2024, https://support.google.com/a/answer/81126 -->
• Gmail requires mail to arrive over an encrypted (TLS) connection.<!-- source: Google, 2024, https://support.google.com/a/answer/81126 -->
• Mail servers typically check blocklists on every incoming connection.<!-- source: RFC 5782 §6, https://www.rfc-editor.org/rfc/rfc5782.html#section-6 -->

Blocklist listing (Listed on ...)

• The blocklists this check queries list mail server IP addresses, not domain names.<!-- source: RFC 5782 §2, https://www.rfc-editor.org/rfc/rfc5782.html#section-2 -->
• Mail servers typically check blocklists on every incoming connection, so a listing can stop mail at the door.<!-- source: RFC 5782 §6, https://www.rfc-editor.org/rfc/rfc5782.html#section-6 -->

Logo in the inbox (check_bimi)

• Gmail shows a BIMI logo only when DMARC is at p=quarantine or p=reject.<!-- source: Google, https://knowledge.workspace.google.com/admin/security/set-up-bimi -->
• For a BIMI logo, Gmail needs a mark certificate (VMC or CMC); the blue checkmark needs a VMC.<!-- source: Google, https://knowledge.workspace.google.com/admin/security/set-up-bimi -->

Propagation and TTL (check_record says wait, check_propagation)

• Every record has a TTL: how long other servers may keep the old copy before asking again.<!-- source: RFC 1035 §3.2.1, https://www.rfc-editor.org/rfc/rfc1035.html#section-3.2.1 -->
• Each resolver keeps the old answer until its cache time (TTL) runs out, so locations update at different moments.<!-- source: RFC 1035 §3.2.1 and RFC 2181 §8, https://www.rfc-editor.org/rfc/rfc2181.html#section-8 -->
• If someone looked the record up before it existed, "not found" can be remembered for a while too.<!-- source: RFC 2308 §5 (negative caching, from the zone's SOA), https://www.rfc-editor.org/rfc/rfc2308.html#section-5 -->

Look-alike domains (check_lookalikes)

• DMARC protects only your exact domain; it cannot stop someone sending from a look-alike name.<!-- source: RFC 7489 §2.4, https://www.rfc-editor.org/rfc/rfc7489.html#section-2.4 -->
• Business email scams caused about 3 billion US dollars in losses reported to the FBI in 2025.<!-- source: FBI IC3 2025 Annual Report (BEC: 24,768 complaints, 3,046,598,558 USD), https://www.ic3.gov/AnnualReport/Reports/2025_IC3Report.pdf -->

Email test (get_email_test: spam placement, alignment)

• DMARC passes only when the From domain matches a domain that SPF or DKIM checked.<!-- source: RFC 7489 §3.1, https://www.rfc-editor.org/rfc/rfc7489.html#section-3.1 -->
• Gmail wants spam complaints below 0.3% of your mail and recommends staying under 0.1%.<!-- source: Google, https://support.google.com/a/answer/81126 and https://support.google.com/a/answer/14229414 -->
• Gmail requires one-click unsubscribe on marketing mail from anyone sending over 5,000 a day.<!-- source: Google, 2024, https://support.google.com/a/answer/81126 -->
• Since November 2025, Gmail has been stepping up enforcement on mail that misses its sender rules.<!-- source: Google, https://support.google.com/a/answer/14229414 -->

Website certificate expiring (TLS certificate expires in, TLS certificate expired on)

• From March 15, 2026, new website certificates last at most 200 days; 100 from 2027, 47 from 2029.<!-- source: CA/Browser Forum Baseline Requirements (Ballot SC-081), https://github.com/cabforum/servercert/blob/main/docs/BR.md -->
• Let's Encrypt certificates last 90 days, and it recommends renewing every 60.<!-- source: Let's Encrypt FAQ, https://letsencrypt.org/docs/faq/ -->
• Our numbers: of 600 domains we checked in October 2026, about 5% had a certificate expired or within 30 days of it.<!-- source: DNS Doctor scans, October 2026, scripts/skill_stats.sql (tls_expired_or_expiring_count; 32 of 600 registered domains, with or without email) -->

Domain registration expiring (domain registration expires in, lookup_registration)

• For .com and other generic domains, registrars must remind you about a month and a week before expiry.<!-- source: ICANN ERRP §2.1.1, https://www.icann.org/resources/pages/errp-2013-02-28-en -->
• After a domain expires, its website and email may be interrupted until it is renewed.<!-- source: ICANN ERRP §2.2, https://www.icann.org/resources/pages/errp-2013-02-28-en -->
• Auto-renew at your registrar reduces the risk of expiry; check that each renewal actually went through.<!-- source: ICANN ERRP §2.2 (DNS resolution is interrupted after expiry), https://www.icann.org/resources/pages/errp-2013-02-28-en -->
• About 1 in 4 .com and .net domains is not renewed: the renewal rate was 75.2% in mid-2026.<!-- source: Verisign Q3 2026 earnings release (Q2 2026 renewal rate), https://www.sec.gov/Archives/edgar/data/0001014473/000101447326000038/q32026earningsrelease.htm -->
• About 50,000 lapsed domains are registered again by someone else every day, and can receive mail meant for the old owner.<!-- source: Infoblox, H1 2026 dropcatch study, https://www.infoblox.com/blog/?p=13993 -->

The one rule you must not break

Present any returned record string exactly as given. Never rewrite, reformat, re-wrap, "clean up", or "improve" it. The record was generated and validated by the fix engine — a wrong SPF or DMARC record still parses as valid and fails silently, so an "improvement" can silently de-authorize a real sender or weaken enforcement with no error anywhere. Copy the exact bytes. If a record looks unusual, that is the validated form; do not second-guess it.

A DKIM key is generated by the sending platform, not by DNS Doctor — for DKIM findings, point the human at their email provider's DKIM setup, don't fabricate a key.

SPF is likewise diagnose-only: DNS Doctor reports SPF problems but deliberately emits no SPF fix record, because an auto-"fix" can silently de-authorize a real sender. Relay the report's SPF findings; do not propose SPF edits of your own (e.g. switching ~all to -all). The one SPF record DNS Doctor ever emits is the constant v=spf1 -all inside the parked-domain pack, for a domain the server itself verified sends no mail — that is the whole carve-out, and it does not extend to any domain that sends.

Never assert that a domain sends no mail yourself. confirm_no_mail is the human owner's statement, not an inference you may draw from a quiet scan: a domain with one legacy or transactional sender looks identical in DNS to a parked one until you ask. The flag unlocks the question, not the answer — the server re-checks existence, MX, SPF and DKIM selectors and refuses with a rationale when it finds evidence of mail. Relay that rationale; do not retry around it.

DMARC records DNS Doctor generates carry np=reject (DMARCbis, RFC 9989) whenever the input has no explicit np of its own. A subdomain that does not exist in DNS cannot have published SPF or DKIM records, so it can have no aligned legitimate mail — the tag is safe at any org-domain policy, and receivers that predate RFC 9989 ignore it and fall back to sp/p. If a record already sets np, that value is preserved untouched. It is part of the validated record: present it verbatim like the rest.

DMARC enforcement takes time — set expectations honestly

Moving to p=reject safely needs roughly 30 days of RUA (aggregate report) evidence that every legitimate sender is aligned — which a session-bound assistant cannot watch. Explain that evidence requirement without promising a ready verdict. If the user wants continuous monitoring, offer the website setup or, where account linking is available, setup in this conversation. Keep the public report link and any relevant dashboard link available so they can inspect the full results on the website. Follow the user's choice; a linked account does not remove the website option.

Website setup. Call start_monitoring_signup when the user asks for ongoing monitoring or chooses website setup. Show its signup_url as a clickable link together with its message. Use the returned URL itself, without changing it; a description of the link without printing the URL does not give the user a way to continue. The call sends no email and creates nothing. Do not promise that opening the link starts monitoring.

In-chat setup. When the user chooses to continue here, use the result's next_steps.in_chat (or top-level in_chat on start_monitoring_signup) to identify the next step for that domain. Treat its contents as state and suggested guidance, subject to these rules and the user's request:

• tool: add_monitored_domain: ask whether they want this domain added if they have not already requested it, then call add_monitored_domain. The host may prompt them to connect their account; only the human authorizes that connection.
• tool: check_domain_verification with a record: show the returned host, type and value exactly as given. The user publishes it at their DNS provider. Pause until they say it is published, then call check_domain_verification. Do not loop verification calls while waiting. If no record is attached, read get_domain_records or call check_domain_verification once to retrieve the enrollment record. A DMARC enrollment record replaces the existing DMARC TXT; the ownership TXT challenge is the alternative if they cannot edit DMARC.
• help on a linked result: if the user cannot make the DNS change themselves, offer the ready help.ticket message for their DNS host's support, or help.web_person for whoever manages their DNS, verbatim; never compose a record. help.support_url, when present, is their host's support page.
• tool: get_readiness: the domain is already verified. For the requested monitoring status, read get_readiness and get_alerts, and explain the returned evidence and blockers. Do not add the domain again or invent a record for a null result.

If linking is unavailable, the connection fails or is declined, offer website setup without repeatedly attempting the connection. If start_monitoring_signup is unavailable in this host, link the returned next_steps.signup_url when present; otherwise direct the user to https://dnsdoctor.dev/dashboard. Do not invent a signup URL. DNS Doctor never publishes a record; the user does.

Never ask a human for their email address to pass to us, and never invent one. Hand over the link and let them sign in on our page themselves — the page offers whichever sign-in methods are available (a social provider or an emailed link).

Do not promise that opening the link starts monitoring. Signing in creates their account and carries the domain over to their dashboard, already filled in — that is all it can do. Daily monitoring is gated on proving they control the domain, so they finish by publishing one DNS record the dashboard shows them: the DMARC record with our report address (it proves ownership and starts the reports), or a TXT record instead if they cannot edit DMARC. The tool's own message says this; relay it verbatim rather than paraphrasing it into "we're now watching your domain".

What continuous monitoring is, so you can describe it accurately: once a domain is verified, DNS Doctor re-scans it daily and keeps the history of every check, emails alerts when a verdict changes or a new sending source appears, ingests the domain's DMARC aggregate (RUA) reports, and derives an enforcement readiness verdict from them — the 30-day alignment evidence this session cannot gather. That is what start_monitoring_signup hands off to; none of it happens from a one-off scan.

Once the domain is verified and the account is linked or a token is configured, the alerts and the readiness verdict are readable through get_alerts and get_readiness — see playbook 5. That is how a later session picks the domain back up without re-deriving anything.

Provider-verification playbook — Microsoft 365 and Google Workspace

Use this when the user wants to check email-provider DNS, not to enroll a new provider account or generate its keys. First establish the domain, provider, and whether the task is sending mail, receiving mail, or both. Ask for the exact public DNS host, type and value issued by that provider's admin screen when comparison is needed. Never request a password, API token or private signing key.

1. Read the supplied names with focused tools. No broad scan is required. For Microsoft 365, when the provider issued selector1 and selector2, use check_record with kind: cname and host: selector1._domainkey (then selector2._domainkey) on the domain. Use check_dkim_selector for each supplied selector to inspect the resolving key. Compare CNAME answers with the tenant's actual issued targets: formats vary, so never manufacture an onmicrosoft.com target or a newer target from the domain name.
2. For Workspace, use its actual selector. google is a common default, not proof of this domain's selector. Read the corresponding TXT using check_record (kind: txt, host: <selector>._domainkey) and inspect the key with check_dkim_selector. If the user has not obtained the key, direct them to generate it in their provider's admin screen; never supply a key from an example or infer one from the domain.
3. Separate expected from observed. Provider-issued public values are the comparison target, not a DNS Doctor generated fix. Relay observed record strings and any engine-generated fix verbatim. Report missing or conflicting records and resolver faults honestly; never compose an authoritative replacement for a missing provider record. The user obtains that record from the provider and publishes it themselves.
4. Keep other senders and receiving mail safe. Use count_spf_lookups or audit_spf_includes for SPF questions; SPF remains diagnose-only. Do not rewrite or merge SPF, and do not suggest changing inbound MX merely because the user is adding an outbound sender. Ask about receiving-mail intent before inspecting a proposed MX cutover.
5. Verify after publication. Wait for the user to say the record is published, then check the exact name/type again. Use check_propagation for regional coverage; a transient or unavailable response is not absence. A published DKIM key does not prove the provider enabled signing, a real message aligns for DMARC, or mail reaches an inbox. Say when provider-side signing status or actual message evidence is still needed.

Playbooks

Six read-orders over the tool surface. Each is an evidence sequence: run the step, read what it rules in or out, and stop when the evidence answers the question. Report what the tools returned. Do not estimate how much mail is affected, how likely a problem is, or what a fix will improve by — DNS Doctor returns evidence, and a number you invented beside it reads as though the scanner produced it.

1. Pre-migration audit — before moving email providers

1. scan_domain the domain. Note the current SPF, DKIM and DMARC verdicts as the "before" state; this is what you will compare against after the cutover.
2. audit_spf_includes. The tree names every provider the domain currently delegates authorization to — including the ones nobody remembers adding. Decision point: each include belongs to a sender that is either staying, going, or unknown. Ask the owner which; do not guess from the vendor name.
3. Read the findings before planning any edit. include_broken is already failing today and is not caused by the migration. pass_all_nested means some delegated record authorizes the whole internet — flag it now, because the migration is the moment to drop that include. include_registrable and include_expiring name includes that are unsafe to carry over.
4. count_spf_lookups to see the lookup cost of the current record, and what headroom the new provider's include needs. The limit is 10 and it is counted recursively.
5. Write the cutover checklist with the owner: which includes are removed, which are added, what DKIM selectors the new provider publishes, whether DMARC policy should be relaxed during the move. You propose; they decide.
6. After each DNS change lands, check_record that one record (spf, dmarc, or txt for a selector) to confirm it is live and in sync, then scan_domain once the whole cutover is done to compare against step 1.

2. Deliverability triage — "our mail isn't arriving"

Work the evidence in this order and say explicitly what each step rules out.

1. scan_domain. If not_registered is true, stop — the domain does not resolve and nothing below applies.
2. Authentication first. Read SPF, DKIM and DMARC. A fail here is the most common cause and the cheapest to fix. temperror rules nothing out — it means the lookup did not complete; retry before drawing any conclusion.
3. Blacklist. A listing explains rejection at the receiving edge even when authentication is perfect. A clean result rules the blocklists we query out, and only those.
4. MX. Check the receiving side if inbound mail is the complaint. Outbound problems are unaffected by MX — say so rather than reporting it as a finding.
5. Alignment. SPF or DKIM passing is not enough for DMARC: the passing identifier must align with the From domain. build_dmarc_upgrade's rationale states what the server found; the report's DMARC detail lines name misaligned or unauthorized sources.
6. Sending IP. If a specific IP is being rejected, check_reverse_dns on it. ptr_missing or mismatch is a real deliverability cause — and the fix belongs to whoever operates the IP, not in the domain's DNS.
7. If the evidence is exhausted and mail still is not arriving, say that plainly: DNS-observable checks cannot see content filtering, reputation, or the receiving side's policy. Do not fill the gap with a guess.

3. Getting to p=reject

1. Scan → build_dmarc_upgrade → the human publishes → re-check: the fix-dmarc skill. A null record's rationale is the answer; never compose a record to fill the gap.
2. Be honest about the next step. The rung after p=quarantine needs roughly 30 days of aggregate-report evidence that every legitimate sender is aligned. You cannot watch that within a session, and there is no shortcut that makes p=reject safe sooner.
3. If the owner has RUA files already, parse_dmarc_report reads one report and shows the per-source aligned share. One report is one window from one receiver — useful evidence, not a readiness verdict.
4. If the user wants the 30-day watch, offer website or in-chat setup as described above. For website setup, show the returned signup_url as a link. The report evidence, once received, supplies the readiness verdict.

4. Parked-domain sweep (MSP / multi-domain)

1. Start from the owner's list of domains they believe send no mail — brand defensives, redirects, old acquisitions. The list comes from them. You may not classify a domain as parked from a scan.
2. Per domain, scan_domain first. It gives you the state to show the owner, and not_registered domains drop out of the sweep immediately.
3. Ask the owner to confirm, domain by domain, that it sends nothing — including transactional mail, monitoring alerts, and any one legacy system. Only then call build_parked_domain_records with confirm_no_mail: true.
4. Read the response before presenting anything. records: null means the server found DNS evidence of mail; relay the rationale and remove that domain from the sweep. A transient failure is a retry, never a pass.
5. On a pass, present the three records verbatim in the order given, with each record's purpose and its check_record verify step. Publishing is the human's decision, one record at a time if they prefer.
6. After publishing, check_record per record (mx, spf, dmarc) to confirm each is live and in sync. Passing rua_email on the build puts spoof attempts against the parked domain into aggregate reports.

5. The operate loop — watching a monitored domain over time

This is the sequence for a domain that is already (or is about to be) under continuous monitoring. Steps 3–5 need a linked account or API token. For a local agent, the owner configures the token in its environment from /dashboard/settings, never in a message.

1. Enroll. Offer website setup with the returned signup_url, or follow the in-chat setup sequence above if the user chooses it. An already verified domain can proceed to the reads without being enrolled again.
2. Verify. The user publishes the engine-generated DMARC reporting record or the ownership TXT alternative, then asks for a verification check. Daily monitoring starts only once ownership verification passes. A pending domain can still use get_domain_records to read the record it needs.
3. Watch. get_alerts on a cadence that suits the human, filtered by domain or type when they only care about one. Page down with before until next_before is null before advancing since, and de-duplicate on id. Report what the log says; the human clears it.
4. Check readiness before proposing enforcement. get_readiness for the domain. ready: false means the blockers are the answer — an unaligned source, too little evidence, an empty window. Say which, and say what would clear it.
5. Propose. Present get_readiness's next_record verbatim when supplied. When the result carries hosted, the domain is on Automatic DMARC: relay hosted.note instead, since its steps are applied from the dashboard. build_dmarc_upgrade is scan-based and cannot supply the report-evidence p=reject step. Never compose a record or treat a null as a gap to fill.
6. The human approves and applies. DNS Doctor never writes DNS. After they publish, check_record with kind: dmarc confirms it landed and is in sync.
7. Re-scan and re-read. scan_domain confirms the verdict flipped; the next get_readiness window shows the effect of the change over time. Then back to step 3 — the loop is the product.

Two things this loop must not do: acknowledge alerts on the human's behalf (there is no such tool, deliberately), and treat a quiet get_alerts page as proof a domain is healthy when you skipped a page to get there.

6. Test a real email

For "is our mail actually signed?", "why does this sender land in spam?", or proving DKIM before tightening DMARC.

1. start_email_test. Print the returned address exactly as returned and ask the user to send ONE email to it from the sender they want to test (the Google Workspace mailbox, the newsletter tool, the app) within the hour. Say plainly that THEY send it, from their own mail app or sending service: the test only works with a message they send themselves, and DNS Doctor does not send it for them. If they have not sent it when you ask, remind them to send it now (the address works about an hour, one message) before you poll.
2. When they say it is sent, get_email_test with the test_id. pending means not arrived yet or still being checked: wait a little and ask again; do not start a new test unless the address has expired.
3. Relay the score with its itemized deductions, then the failing parts first: DMARC result and disposition, then which DKIM signature (if any) verified and aligned, then SPF. A temperror is a lookup that did not complete — never a failure, and it was not scored. A version 2 score is one decimal out of 10: a 9.9 means something small was deducted or a key check could not complete, and a 10 has nothing deducted.
4. Relay result.estimates per provider as estimates, never as a promise of delivery: accepted_pct comes from that provider's published sender rules, a DMARC fail under a quarantine or reject policy and a blocklisted sending IP, inbox_pct from the AI read calibrated on labelled mail, except that a DMARC fail under a quarantine or reject policy caps it at 5 (and sets it to 5 with no AI read). null means there is no inbox estimate; say so rather than guessing one. Relay the basis lines: they say where each number came from. sender_requirements shows which published rule this message missed; the spam complaint rate is visible only to the provider.
5. Fixes: present result.dmarc.fix.record verbatim at result.dmarc.fix.host when supplied, or relay result.dmarc.fix_withheld when the fix is withheld (a domain on Automatic DMARC gets its steps from the dashboard). SPF stays diagnose-only; DKIM keys come from the sending provider (see the provider-verification playbook). Never compose a record.
6. After the human changes something, a NEW test proves it: each address takes one message.

7. Logo in the inbox (BIMI)

For "how do we get our logo in Gmail?", "does our BIMI work?", or "why doesn't our logo show?".

1. check_bimi with the exact sending domain (a subdomain is checked as itself). Pass logo_url (and certificate_url, when they have one) only for a logo the user named.
2. Relay eligibility honestly: mailboxes says what our checks saw and what is still required, never that a logo will show. Each mailbox decides. Gmail needs a VMC or CMC certificate (the checkmark only with a VMC), Apple Mail needs a VMC, Yahoo/AOL show logos only for senders with enough volume and reputation, and Outlook does not support BIMI.
3. needs_enforcement comes first: BIMI needs DMARC at p=quarantine or p=reject. Use the DMARC ladder ("Getting to p=reject" above); never skip a step to get a logo sooner.
4. Present generated.record verbatim at generated.host when supplied. When it is null, relay generated.rationale. Never compose a BIMI record yourself.
5. unknown means a lookup or download failed: try again shortly. Relay any next_steps links as clickable links.

Learn more

The scoring methodology (how SPF lookups are counted, why p=reject needs an alignment signal, what "temperror ≠ fail" means) is published at https://dnsdoctor.dev/methodology.