DomainCanary Start free

API and MCP documentation

Check a domain's DMARC, SPF and DKIM records from a script, a CI job or an AI assistant. The free JSON API and the MCP server need no account and no key.

SectionAddressYou need
Free JSON APIhttps://domaincanary.com/c/{domain}?format=jsonNothing
MCP serverhttps://domaincanary.com/mcpNothing
GitHub Actiondomaincanary/spf-preflight-action@v1Nothing
Account APIhttps://domaincanary.com/api/v1A paid plan and an API key
WebhooksA public https address of yoursA paid plan

Free JSON API

These calls run the same checks as the free tools. The full schema is at /openapi.json in OpenAPI 3.1.

Check a domain

GET /c/{domain}?format=json looks up the domain's DMARC, SPF and DKIM records, where its DMARC reports go, its MX records, whether its mail servers are on the SpamCop blocklist, MTA-STS, TLS-RPT and BIMI.

curl "https://domaincanary.com/c/example.com?format=json"

The response lists every problem in issues, worst first. Some issues carry a fix with the DNS record to publish.

Response, trimmed to two checks

{
  "domain": "example.com",
  "url": "https://domaincanary.com/tools/checkup/example.com",
  "complete": true,
  "issues": [
    {
      "check": "bimi",
      "level": "warn",
      "message": "No BIMI record is published. BIMI needs p=quarantine or p=reject."
    }
  ],
  "checks": {
    "dmarc": {
      "status": "ok",
      "summary": "p=reject",
      "detail": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com"
    },
    "spf": {
      "status": "ok",
      "summary": "4/10 lookups",
      "detail": "v=spf1 include:_spf.google.com include:servers.mcsv.net -all"
    }
  },
  "blocklists_checked": ["SpamCop"]
}

When complete is false, a DNS lookup did not finish and the list of issues may be short. Call again. With format=txt you get the same report as plain text.

SPF change check

POST /api/v1/spf-preflight compares the SPF record you plan to publish with the record the domain publishes today.

curl -X POST https://domaincanary.com/api/v1/spf-preflight \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "record": "v=spf1 include:_spf.google.com -all"}'

Response, trimmed

{
  "checked_at": "2026-11-10T21:43:38.000Z",
  "domain": "example.com",
  "verdict": "fail",
  "lookups": { "published": 4, "proposed": 3, "limit": 10 },
  "removed": [
    {
      "term": "include:servers.mcsv.net",
      "ranges": ["198.51.100.20/32"],
      "ipv4_addresses": 1,
      "ipv6_ranges": 0,
      "traffic": null
    }
  ],
  "added": [],
  "lost": { "ipv4_addresses": 1, "ipv6_ranges": 0 },
  "traffic": { "checked": false, "reason": "no-key" },
  "findings": [
    { "level": "error", "text": "198.51.100.20 changes from pass to fail." }
  ]
}
verdictMeaning
failThe new record breaks SPF, or a tested address loses its SPF pass.
warnWe found something to check before you publish. The findings list has the details.
passNo tested address loses its SPF pass.
unchangedThe new record covers the same senders as today's record.

Rate limit on the free API

Each IP address has 30 lookups, shared with the free tools on the site. A domain check counts as 5 lookups, or 6 when the domain has mail servers. An SPF change check counts as 2. Past 30, the API returns 429 with a Retry-After header, and the count starts again 10 minutes after your last call.

MCP server

Our MCP server at https://domaincanary.com/mcp lets an AI assistant run the tools below, which are all read-only. The server uses the Streamable HTTP transport and needs no sign-in.

ToolWhat it doesInput
check_domainReads a domain's live DMARC, SPF and DKIM records and lists what to fix, with the records to publish.domain, selector
build_spfBuilds one SPF record for the services that send a domain's mail and counts its DNS lookups.senders, domain, ip4, ip6, all
explain_bounceExplains a bounce message or an SMTP error and lists what to change.text
analyze_reportReads a DMARC aggregate report and lists the sending IP addresses that failed.file, report_xml (file is an upload in ChatGPT)

Add the MCP server to an assistant

In Claude or ChatGPT, add a custom connector with the address above. Check your domain from ChatGPT or Claude has the steps for both. In Claude Code, run this command:

claude mcp add --transport http domaincanary https://domaincanary.com/mcp

Any other MCP client takes the same address. To list the tools from a terminal, send this request:

curl -X POST https://domaincanary.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Rate limit on the MCP server

Everyone who uses the server shares an allowance of calls and DNS lookups, and each caller gets a part of it every ten minutes. Past your part, the server refuses the call and the response gives the time to wait. Nothing you send is written to our database, to disk or to a log. The privacy policy lists what each assistant sends with a call.

GitHub Action

The SPF pre-flight action runs the SPF change check on a pull request and fails the check when the new record would break mail.

- uses: domaincanary/spf-preflight-action@v1
  with:
    domain: example.com
    record: "v=spf1 include:_spf.google.com -all"
    api-key: ${{ secrets.DOMAINCANARY_API_KEY }}

Without api-key, the action tests the ranges in both records. With it, the test also covers the senders in your DMARC reports. Check an SPF change in a pull request has a workflow that reads the record from your DNS repository, with recipes for octoDNS, DNSControl and Terraform.

Account API

With an API key, a script can check domains in bulk and manage the domains in your account. Most calls need a paid plan.

API key

Create a key on your account page. We show it once, so copy it then. Send it as a bearer token:

curl -X POST https://domaincanary.com/api/v1/check \
  -H "Authorization: Bearer $DOMAINCANARY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["example.com"]}'

Response

{
  "checked_at": "2026-11-10T21:43:38.000Z",
  "rows": [
    {
      "domain": "example.com",
      "verdict": "protected",
      "dmarcPolicy": "reject",
      "dmarcRua": true,
      "spf": "ok",
      "spfLookups": 4,
      "dkim": "found",
      "dkimSelectors": ["google"],
      "notes": ""
    }
  ]
}

Account API endpoints

CallPlanWhat it does
POST /api/v1/spf-preflightNo key neededThe SPF change check. With a key, it also compares the ranges you remove with the senders in your DMARC reports, and traffic.reason has the cause when it could not. Limit with a key: 20 calls, and 100 calls a day.
POST /api/v1/checkPaid plansChecks DMARC, SPF and DKIM for up to 200 domains. Send {"domains": [...]}. Limit: 30 calls.
GET /api/v1/domainsPaid plansLists the domains in your account. Returns {"domains": [{"name", "group", "added_at", "verified"}]}, with added_at in Unix seconds.
POST /api/v1/domainsPaid plansAdds up to 100 domains. Send {"domains": [...]}. On the Business plan and up, add "group": "Name" to put them in a group, which we create if it is new. Returns {"added": [...], "skipped": [{"name", "reason"}]}. Limit: 10 calls.
GET /api/v1/domains/{name}/recordsPaid plansLists the DNS records we ask you to publish for a domain. Returns {"domain", "records": [{"host", "type", "value", "state"}]}, with host relative to the domain and a state of live, waiting, broken or check failed. Limit: 60 calls.

Each limit counts calls per account, and the count starts again 10 minutes after your last call, or at midnight UTC for the daily limit.

Account API errors

Every error response is a JSON object whose error field has the cause.

StatusMeaning
400The body is not valid JSON.
401The key is missing, or it matches no account.
403Your plan does not include this call.
404The domain is not in your account.
413The body is larger than 64 KB.
422A field is missing or has the wrong shape.
429You have reached a limit.
503The DNS lookup for the SPF change check did not finish. Try again.

Webhooks

On a paid plan, we post the alerts we email you as JSON to a public https address you give us, on port 443. Add the address under Webhook on your notifications page. We show the signing secret once, when you first save the address. Copy it then. Press Send a test to get this message:

{
  "id": "evt_3f9c1a7b2d4e5f60718293a4",
  "type": "webhook.test",
  "created_at": "2026-11-10T21:43:38Z",
  "domain": null,
  "domains": [],
  "subject": "DomainCanary is connected",
  "summary": "Alerts for your domains will arrive at this address.",
  "url": "https://domaincanary.com/dashboard"
}

We send each message once, wait 5 seconds for a 2xx response and don't follow redirects.

Webhook event types

typeWe send it when
sender.failingA new sender fails DMARC.
sender.regressedA sender that was passing DMARC starts failing.
sender.new_passingA new sender appears and passes DMARC.
sender.confirmed_passingA sender you approved passes DMARC.
ip.listedAn approved sender's IP address is on a blocklist.
dmarc_record.changedYour DMARC record is gone or broken, its policy is weaker, or our reporting address is missing from it.
dns_record.changedYour SPF record or a DKIM key is gone or broken.
provider.failingA provider starts failing DMARC on several of your domains.
hosted_spf.changedThe sender addresses in your hosted SPF record changed.
watch_list.worseThe DMARC or SPF record of a domain on your watch list got worse.
webhook.testYou pressed Send a test.

Verify the webhook signature

Each message carries a DomainCanary-Signature header of the form t=<unix time>,v1=<signature>. The signature is the HMAC-SHA256 of the time, a dot and the raw body, keyed with the whole signing secret, whsec_ included, and written in hex. Refuse a message whose time is more than 5 minutes from yours.

import { createHmac, timingSafeEqual } from "node:crypto";
import { Buffer } from "node:buffer";

// header: the DomainCanary-Signature header.
// rawBody: the body as received, before parsing.
function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(expected, given);
}

Contact

Write to contact@domaincanary.com. The code we publish is on GitHub.