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.
| Section | Address | You need |
|---|---|---|
| Free JSON API | https://domaincanary.com/c/{domain}?format=json | Nothing |
| MCP server | https://domaincanary.com/mcp | Nothing |
| GitHub Action | domaincanary/spf-preflight-action@v1 | Nothing |
| Account API | https://domaincanary.com/api/v1 | A paid plan and an API key |
| Webhooks | A public https address of yours | A 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." }
]
}
verdict | Meaning |
|---|---|
fail | The new record breaks SPF, or a tested address loses its SPF pass. |
warn | We found something to check before you publish. The findings list has the details. |
pass | No tested address loses its SPF pass. |
unchanged | The 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.
| Tool | What it does | Input |
|---|---|---|
check_domain | Reads a domain's live DMARC, SPF and DKIM records and lists what to fix, with the records to publish. | domain, selector |
build_spf | Builds one SPF record for the services that send a domain's mail and counts its DNS lookups. | senders, domain, ip4, ip6, all |
explain_bounce | Explains a bounce message or an SMTP error and lists what to change. | text |
analyze_report | Reads 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
| Call | Plan | What it does |
|---|---|---|
POST /api/v1/spf-preflight | No key needed | The 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/check | Paid plans | Checks DMARC, SPF and DKIM for up to 200 domains. Send {"domains": [...]}. Limit: 30 calls. |
GET /api/v1/domains | Paid plans | Lists the domains in your account. Returns {"domains": [{"name", "group", "added_at", "verified"}]}, with added_at in Unix seconds. |
POST /api/v1/domains | Paid plans | Adds 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}/records | Paid plans | Lists 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.
| Status | Meaning |
|---|---|
400 | The body is not valid JSON. |
401 | The key is missing, or it matches no account. |
403 | Your plan does not include this call. |
404 | The domain is not in your account. |
413 | The body is larger than 64 KB. |
422 | A field is missing or has the wrong shape. |
429 | You have reached a limit. |
503 | The 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
type | We send it when |
|---|---|
sender.failing | A new sender fails DMARC. |
sender.regressed | A sender that was passing DMARC starts failing. |
sender.new_passing | A new sender appears and passes DMARC. |
sender.confirmed_passing | A sender you approved passes DMARC. |
ip.listed | An approved sender's IP address is on a blocklist. |
dmarc_record.changed | Your DMARC record is gone or broken, its policy is weaker, or our reporting address is missing from it. |
dns_record.changed | Your SPF record or a DKIM key is gone or broken. |
provider.failing | A provider starts failing DMARC on several of your domains. |
hosted_spf.changed | The sender addresses in your hosted SPF record changed. |
watch_list.worse | The DMARC or SPF record of a domain on your watch list got worse. |
webhook.test | You 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.