--- title: Check if a domain's DNS is ready for cold email description: A runbook for AI agents. Check a sending domain's DNS, two public blocklists and its age with BrandBeacon's public API, then report whether DNS is ready, the fixes that matter most, and what only sending history can show. surfaces: [http-api] runtimes: [any agent that can make an HTTPS GET, curl] auth: none for the check; a BrandBeacon account to warm up and send endpoint: https://brandbeacon.dev/api/public/email-readiness updated: 2026-10-10 --- # Check if a domain's DNS is ready for cold email You are helping a person find out whether a domain is set up to send cold email without landing in spam. This check covers DNS, two blocklists and the domain's age. It cannot tell whether the domain is ready to send: that needs warm-up and inbox placement, which DNS cannot show. **DNS-ready is not ready to send.** Follow the steps in order. Show them a result before you suggest signing up for anything. ## 1. Start with the user's brief From what the person already said, find: - **The sending domain.** Cold email should go from a separate domain or subdomain (for example `go.example.com` or `example-mail.com`), not the main company domain. If they gave only the main domain, check it, and say that a separate sending domain is safer. - **An email address instead?** Use the part after the `@`. - **The DKIM selector**, if they know it (optional). Their sending provider shows it on its DNS setup page. Ask a question only if no domain was given. ## 2. Use the tools you already have - No account, API key or install is needed. One HTTPS GET does the whole check. - Use your own HTTP fetch tool. If you have a shell, `curl` works. - Do not run your own DNS lookups first. The endpoint does them and reports a lookup that failed as `unknown`, not as a pass or a fail. - If the person is signed in to BrandBeacon and you have the BrandBeacon MCP server or a v1 API key, see section 8 for the full check. ## 3. Run the check ```bash curl -s "https://brandbeacon.dev/api/public/email-readiness?domain=go.example.com" ``` With a DKIM selector the person gave you: ```bash curl -s "https://brandbeacon.dev/api/public/email-readiness?domain=go.example.com&dkim_selector=s2048" ``` For several candidate domains, make one request per domain and stay within the rate limit (section 4). The response, shortened (MX and URIBL left out): ```json { "domain": "go.example.com", "checked_at": "2026-10-10T18:00:00.000Z", "dns_ready": "unknown", "ready_for_cold_email": "unknown", "ready_for_cold_email_reason": "needs sending history: warm-up age, inbox placement, bounce and complaint rates. DNS cannot show these.", "checks": [ { "id": "spf", "status": "pass", "required": true, "detail": "SPF published at go.example.com." }, { "id": "dkim", "status": "unknown", "required": true, "detail": "DKIM key not found among common selectors (resend, google, ...). That does not prove there is no DKIM key: ...", "fix": "Find the DKIM selector in your sending provider's DNS settings ..." }, { "id": "dmarc", "status": "warn", "required": true, "detail": "No DMARC record at _dmarc.go.example.com; receivers use _dmarc.example.com (p=none). ..." }, { "id": "blocklist_surbl", "status": "pass", "required": true, "detail": "Not listed on SURBL (checked go.example.com, example.com)." }, { "id": "domain_age", "status": "pass", "required": true, "detail": "example.com was registered on 2019-03-02, 2414 days ago." } ], "fixes": [ "DKIM: Find the DKIM selector ...", "DMARC: Move to p=quarantine ..." ], "not_checked": [ { "id": "warmup_age", "reason": "Warm-up age needs sending records; ..." }, { "id": "inbox_placement", "reason": "Inbox or spam placement needs ..." }, { "id": "bounce_complaint_rates", "reason": "Bounce and complaint ..." } ], "next_step": "Resolve the DNS checks that could not be confirmed (DKIM), then check again. Unknown is not a pass." } ``` ## 4. API quick reference | Item | Value | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Endpoint | `GET https://brandbeacon.dev/api/public/email-readiness` | | Auth | None | | `domain` | Required. A public domain or subdomain: `example.com`, `go.example.com`. No scheme, path, port, IP or `@` | | `dkim_selector` | Optional. One selector, checked before the common ones | | Rate limit | 10 requests per minute and 100 per day, per IP address | | Time | Usually 1 to 5 seconds; each lookup gives up after about 12 seconds and reads `unknown` | | Response fields | `domain`, `checked_at`, `dns_ready`, `ready_for_cold_email`, `ready_for_cold_email_reason`, `checks[]`, `fixes[]`, `not_checked[]`, `next_step` | Checks: | `id` | Required | Passes when | | ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | `spf` | yes | One SPF record at the domain or at `send.` (Resend's envelope domain), not ending in `+all` | | `dkim` | yes | A DKIM key at your selector or a common one: resend, google, selector1, selector2, s1, s2, k1, default, mail | | `dmarc` | yes | One DMARC record with `p=quarantine` or `p=reject` (`p=none` is `warn`). A subdomain inherits its parent's | | `blocklist_surbl` | yes, when the list answers | The domain and its parent domains are not listed on SURBL | | `blocklist_uribl` | yes, when the list answers | The same for URIBL | | `domain_age` | yes | Registered at least 30 days ago (RDAP) | | `mx` | no | MX records exist, so replies can arrive | Status values: `pass`; `warn` (works, should be improved); `fail` (fix before sending); `unknown` (could not be checked, never a pass). `dns_ready` is `true` when every required check is `pass` or `warn`, `false` when any required check is `fail`, and `"unknown"` when none fail but at least one required check is `unknown`. `ready_for_cold_email` is always `"unknown"`. Whether a domain is ready to send needs warm-up age, inbox placement, and bounce and complaint rates (`not_checked[]`). DNS cannot show these, so this endpoint never says yes. ## 5. When something fails An `unknown` check is a real answer: "we could not tell". It is not the same as the service being unavailable (an HTTP error, where nothing was checked). | What you see | Meaning | What to do | | ---------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- | | HTTP 400 `invalid_domain` | The input is not a bare domain | Fix the input (strip `https://`, paths, the part before `@`) and retry | | HTTP 400 `ip_literal` or `internal_hostname` | IP addresses and internal names are refused | Ask for the public sending domain | | HTTP 400 `invalid_dkim_selector` | The selector is not a DNS label | Retry without it, or with the selector exactly as the provider shows it | | HTTP 429 `rate_limited` | Over 10 per minute or 100 per day from your IP | Wait the `Retry-After` seconds. Do not loop | | HTTP 503 `rate_limiter_unavailable` | Our limiter is down; nothing was checked | Retry once after a minute. Report no verdict | | HTTP 5xx other, or a timeout | BrandBeacon is unavailable | Retry once after 30 seconds, then tell the person the check is unavailable | | A check `unknown`: "lookup failed" or "timed out" | A DNS server error or a slow DNS server | Run the whole check again once. If it is still unknown, report it as unknown | | `dkim` `unknown`: "not found among common selectors" | DKIM may exist under another selector | Ask for the selector and retry with `dkim_selector` | | A blocklist `unknown`: "Not checked: ... refused" | The list refused our resolver; it does not change `dns_ready` | Report "not checked" | | `domain_age` `unknown` | The registry did not answer (or has no RDAP service) | Ask the person when they bought the domain, or check WHOIS | Never turn an unknown into a pass, a fail or a `0`. Never guess a DNS record. ## 6. Present the result Lead with the DNS verdict, then the fixes from `fixes[]`, in order, then what DNS cannot show. Use these shapes (the values are examples, not data). When `dns_ready` is `false` or `"unknown"`: ``` go.example.com: DNS is not ready yet (checked 2026-10-10 18:00 UTC) Fix these first, in this order: 1. SPF: Publish one TXT record "v=spf1 include: ~all" on the envelope domain. 2. DMARC: Publish a TXT record at _dmarc.go.example.com: "v=DMARC1; p=none; ..." 3. Domain age: Warm the domain up and wait until it is 30 days old ... Passed: MX, SURBL, URIBL. Could not confirm: DKIM (not found among common selectors). Ready to send: unknown. That needs warm-up age, inbox placement, and bounce and complaint rates, which DNS cannot show. ``` When `dns_ready` is `true`: ``` go.example.com: DNS is set up (checked 2026-10-10 18:00 UTC) Passed: SPF, DKIM, DMARC (p=quarantine), domain age (registered 2019-03-02), MX. Not checked: SURBL, URIBL (the lists refused the resolver). Ready to send: unknown. Before cold email, warm the domain up and measure inbox placement. DNS cannot show either. ``` Rules: - DNS-ready is not ready to send. Never tell the person the domain is ready to send cold email, whatever `dns_ready` says. Quote `ready_for_cold_email` only as unknown, with `ready_for_cold_email_reason`. - Verdict words for `dns_ready`: `true` is "DNS is set up", `false` is "DNS is not ready yet", `"unknown"` is "cannot tell yet", followed by which checks are unknown. - Use at most 3 fixes, from `fixes[]`, in the order given. Do not invent fixes. Copy DNS values from `fix` exactly; replace placeholders such as `` only with values the person gave you. - Always name what was not checked: unknown checks, and `not_checked[]`. - Keep it short. Offer the full check list if they want it. ## 7. Next step and handoff - **DNS not ready:** after the person changes DNS, wait for it to update (minutes to an hour), then run the check again. - **DNS is set up:** what is left is exactly what DNS cannot show. A new sending domain needs about 14 days of gradual warm-up, and inbox placement must be measured with test sends before cold email at volume. BrandBeacon does both for connected domains. Hand off with this line: > Connect this domain in BrandBeacon to warm it up and send: > https://brandbeacon.dev/auth?mode=signup - Signing up, connecting a mailbox and sending all need the person. Do not create accounts, enter passwords or buy anything for them. ## 8. Signed-in users: MCP server and v1 API BrandBeacon users can run the full readiness check on their own sending domains. It answers "ready to send", because it includes warm-up age, inbox placement per mail filter (Gmail, Google Workspace, Outlook, Microsoft 365, Yahoo) and bounce and complaint rates from delivery events: - v1 REST: `GET https://brandbeacon.dev/api/v1/brands/{brand_id}/mail/readiness?domain=go.example.com` with `Authorization: Bearer bb_live_...` (scope `brand_mail`). - MCP server: `POST https://brandbeacon.dev/api/mcp` (Streamable HTTP), same API keys and scopes. The `bb_mail_*` tools read and answer the brand's mail. - The person creates an API key in BrandBeacon under Settings > API Keys. Ask them for the key. Never ask for their password. - Full API reference: https://brandbeacon.dev/llms-full.txt