Keys and limits
Most endpoints work without a key, limited to 30 requests every ten minutes from one IP address. With a key the limit goes up to 2,000 per ten minutes, and the bulk endpoint opens up. Keys are issued on request while the API is in early access.
Send the key as a bearer token (an X-API-Key header works too):
curl https://ihateemail.io/api/check?domain=example.com \
-H "Authorization: Bearer ihe_your_key"
Errors come back with a matching HTTP status and a JSON body like {"error": "Enter a domain like example.com"}. You'll see 400 for bad input, 401 when a key is required, 404 for an unknown or expired test, and 429 when you hit the limit.
Check a domain or IP
GET /api/check?domain=example.com&selector=optional
Runs the full domain report: SPF, DKIM, DMARC, blacklists, MX and TLS, plus domain age, DNSSEC, MTA-STS, TLS-RPT and BIMI. Pass an IPv4 address instead of a domain to get its blacklist listings and reverse DNS. The optional selector checks one DKIM selector instead of the common list.
{
"kind": "domain",
"domain": "example.com",
"score": 81,
"sections": [
{"name": "DMARC", "findings": [
{"s": "fail", "t": "No DMARC record",
"d": "Gmail, Yahoo and Microsoft require DMARC for bulk senders…",
"fix": "Add a TXT record at _dmarc.example.com: …"}
]}
]
}
Generate records
GET /api/generate?domain=example.com&keygen=1&selector=s2026
Works out the SPF, DKIM, DMARC and MX records the domain should publish, starting from what it publishes today. Existing includes and DMARC tags are kept, duplicates are merged, and providers are detected from MX (Google Workspace and Microsoft 365 get their exact records). Each record comes with an action of add, replace, keep or configure, where configure means it's a step in the provider's admin console rather than a record you can paste.
With keygen=1 you also get a fresh 2048-bit DKIM key pair for your own mail server, as a TXT record plus a private_key field. The private key is generated for that one response and never stored, so save it before you close anything.
{
"domain": "example.com",
"providers": ["Google Workspace"],
"records": [
{"type": "TXT", "name": "example.com",
"value": "v=spf1 include:_spf.google.com ~all",
"action": "replace",
"why": "Adds include:_spf.google.com so mail from your provider passes SPF."}
],
"notes": []
}
Bulk checks
POST /api/bulk (key required)
Checks up to 100 domains in one call, six at a time, which takes roughly ten seconds for thirty domains. Set generate to get the records for each one too. By default the generator suggests moving DMARC from p=none to quarantine once SPF and DKIM are in place; set enforce to false if you only want fixes that affect delivery.
curl -X POST https://ihateemail.io/api/bulk \
-H "Authorization: Bearer ihe_your_key" \
-d '{"domains": ["example.com", "example.org"], "generate": true, "enforce": false}'
Each result has the domain, its score, the warn and fail findings as issues, and the generated records when you asked for them.
Every check also returns readiness, which is separate from the score. It has a config gate (the mail records in DNS, or a message's authentication results) and an infra gate (the sending server's reverse DNS and HELO, which Spamhaus requires from November 2026). Each gate has a state of blocked, unverified, warnings or ready, with the reasons behind it. A domain with no SPF, DKIM, DMARC or MX at all gets nomail instead, since DNS can't tell whether it is meant to send mail. One critical failure blocks a gate however high the score is. A domain check can't see your sending server, so its infra gate is always unverified; send a test email to settle it.
Monitoring webhooks
Watch domains from the Monitors page in your dashboard (or straight after checking one) and we re-check each of them once a day. When something changes (a new problem, a new blacklist listing, or a problem that went away) we email you, and if you saved a webhook URL we POST the same changes to it, one call per daily run covering all your domains. Nothing is sent on days when nothing changed. Slack incoming webhooks work as they are, because the payload carries a ready-made text field.
{
"event": "domains.changed",
"checked_at": 1793001600,
"dashboard_url": "https://ihateemail.io/dashboard#monitors",
"changes": [{
"domain": "example.com", "score": 81, "previous_score": 96,
"new": [{"s": "warn", "section": "DMARC", "t": "DMARC policy is p=none", "fix": "Move to p=quarantine…"}],
"resolved": []
}],
"text": "1 watched domain changed since the last check…"
}
Each request has an X-Ihateemail-Signature header: sha256= followed by the HMAC-SHA256 of the raw body, keyed with the signing secret shown on the Monitors page. Check it before trusting the payload. The "Send a test event" button there sends the same shape with "event": "test". Webhook URLs have to be https and on a public address.
expected = "sha256=" + hmac.new(secret.encode(), request_body, "sha256").hexdigest()
hmac.compare_digest(expected, request.headers["X-Ihateemail-Signature"])
Test inbox
POST /api/test
Creates a one-time address. Send an email to it, then poll the status endpoint every couple of seconds until it's done. Each address accepts one message and expires after 24 hours.
{"id": "3f9a6c21d0b4", "address": "[email protected]"}
GET /api/test/id
Returns a status of waiting, analyzing, done or error. When it's done, result holds the full message report, with sections for authentication, sending server, headers, content and SpamAssassin.
Analyze a message
POST /api/analyze
Send the raw message source (or only the headers) as the request body, up to 5 MB. You get the same report as a test email, minus the checks that need the SMTP connection itself, plus the receiving server's verdict from its Authentication-Results header.
curl -X POST https://ihateemail.io/api/analyze --data-binary @message.eml
Response shapes
A finding has s (one of pass, warn, fail or info), t (a one-line title), d (the detail, often the record itself) and fix (what to do, empty when nothing needs doing). Findings are grouped into sections, and every report carries a score from 0 to 100 that drops 15 points for each fail and 4 for each warning.
A record from the generator has type, name, value, action and why. Values in brackets, like "(generated by Microsoft 365)", come from the provider's console and can't be pasted directly.
MCP server
AI assistants that speak MCP (Claude, Cursor, VS Code and others) can run the same checks. The server is at https://ihateemail.io/mcp (Streamable HTTP). It needs no key and has the same limits as the anonymous API.
claude mcp add --transport http ihateemail https://ihateemail.io/mcp
For clients configured with JSON:
{"mcpServers": {"ihateemail": {"url": "https://ihateemail.io/mcp"}}}
It has two tools. check_domain takes a domain or public IPv4 address (and an optional DKIM selector) and returns the score, readiness, each problem with its fix, the checks that passed and a link to the full report. generate_records returns the records to publish, each marked add, replace, keep or configure, as in Generate records. Key generation is left out on purpose, so a private key never ends up in a chat log.