Domain authentication
Check a domain's SPF record the way receiving mail servers read it, from the API or an AI app.
Domain authentication reads a domain’s SPF record and tells you what is wrong with it. Today that is SPF only: the record’s syntax, its DNS lookup count and the policy for servers it does not list, evaluated the way receiving mail servers evaluate it. Try it in your browser with the free SPF Record Checker.
Request
curl "https://api.kavik.email/api/v1/domain/example.com/audit" \
-H "X-API-Key: eva_your_key"The domain is a bare domain such as example.com. An internationalized domain works in Unicode or in its xn– form. The optional checks query parameter is a comma list of the records to check. Only spf exists today, and leaving checks out checks every record we offer, so the two give the same answer now:
curl "https://api.kavik.email/api/v1/domain/example.com/audit?checks=spf" \
-H "X-API-Key: eva_your_key"Cost and caching
A call costs 1 verification. It is free when every record you asked for could not be checked: the call is refunded and the response says so in incomplete. A malformed request is refused and not charged.
We keep a finished report for 5 minutes, and a report with a check we could not finish for 60 seconds. API calls and AI-app calls share those reports. If you fix a record, the change shows up once the old record’s TTL in DNS has passed, and a call within 5 minutes of an earlier one for the same domain may return that earlier report.
Response
| Field | Type | Meaning |
|---|---|---|
domain |
string | The domain as we checked it, in lower case |
domain_unicode |
string | The domain in Unicode. Present only for an internationalized domain |
checked_at |
string | When the report was made, ISO 8601 |
status |
enum | fail when any finding is critical, warn when any is a warning, incomplete when a check could not finish, otherwise pass |
counts |
object | critical, warning and info: how many findings of each severity |
incomplete |
array | The checks we couldn’t finish. Empty when all finished |
spf |
object | The SPF section, below |
findings |
array | What we found. Empty on a healthy domain |
livemode |
boolean | true for a live key, false for a test key |
incomplete means we couldn’t finish this check, for example because a DNS server did not answer in time. It is not a verdict on the domain, so ask again a minute later.
This is the report a test key gets for example.com:
{
"data": {
"domain": "example.com",
"checked_at": "2026-01-01T00:00:00Z",
"status": "pass",
"counts": {
"critical": 0,
"warning": 0,
"info": 0
},
"incomplete": [],
"spf": {
"status": "pass",
"record": "v=spf1 include:_spf.example.com -all",
"lookups": {
"count": 1,
"limit": 10,
"void": 0,
"void_limit": 2,
"partial": false
},
"all": "-all",
"ip4_addresses": 256,
"ip6_prefixes": 1,
"tree": [
{
"term": "include:_spf.example.com",
"domain": "_spf.example.com",
"lookups": 1
}
]
},
"findings": [],
"livemode": false
}
}The SPF section
| Field | Type | Meaning |
|---|---|---|
status |
enum | pass, warn or fail from the findings, missing when the domain publishes no SPF record, error when we couldn’t finish the check, skipped when you did not ask for it |
record |
string | The SPF record as published |
lookups |
object | The DNS lookups the record needs, below |
all |
string | How the record ends: -all, ~all, ?all or +all. Left out when it has no ending |
ip4_addresses |
integer | IPv4 addresses the record lists, counted through every include and redirect |
ip6_prefixes |
integer | IPv6 prefixes the record lists |
tree |
array | One entry per term that costs a lookup, with its own children for the records it pulls in |
A field that does not apply is left out of the response, not returned empty: record, lookups, all, ip4_addresses, ip6_prefixes and tree appear only when the record has something to put in them.
lookups holds count, limit, void, void_limit and partial. Receiving mail servers allow 10 terms that query DNS and 2 lookups that return nothing. count keeps going past 10, so it can tell you how many lookups the record needs, not only that it is over. When partial is true, the real count and void are at least the values shown.
Each tree entry has term, domain and lookups (its own cost plus its children’s), and, when they apply, void, error, unexpanded and children.
Findings
| Field | Meaning |
|---|---|
id |
A stable name for the finding, such as spf.lookup_limit_exceeded |
check |
The record it belongs to. spf today |
severity |
critical, warning or info |
title |
One line saying what is wrong |
detail |
Why it matters |
evidence |
The terms or values behind the finding |
fix |
What to change |
ref |
The standard the finding rests on |
doc_url |
A link to a page that explains the finding and how to fix it, when one exists. |
A record that needs 13 lookups returns this in spf.lookups and as its first finding:
{
"lookups": {
"count": 13,
"limit": 10,
"void": 0,
"void_limit": 2,
"partial": false
},
"findings": [
{
"id": "spf.lookup_limit_exceeded",
"check": "spf",
"severity": "critical",
"title": "SPF needs 13 DNS lookups; the limit is 10",
"detail": "Receivers stop after 10 terms that query DNS (include, a, mx, ptr, exists and redirect, counted through every included record) and return permerror. Any server not matched before that point fails SPF.",
"evidence": [
"\"include:_spf.crm.example.org\" costs 4",
"\"include:_spf.desk.example.org\" costs 3",
"\"include:_spf.news.example.org\" costs 2",
"\"include:spf.billing.example.org\" costs 2",
"\"a\" costs 1",
"and 1 more"
],
"fix": "Remove includes for services you no longer use, replace a and mx terms with the ip4 and ip6 ranges they stand for, and move services with large records to a subdomain with its own SPF record. Aim for 8 lookups or fewer so a provider change doesn't push you over.",
"ref": "RFC 7208 §4.6.4",
"doc_url": "https://kavik.email/tools/errors/spf-too-many-dns-lookups/"
}
]
}Errors
| Status | code |
When |
|---|---|---|
| 400 | INVALID_DOMAIN |
The domain is not a bare domain such as example.com |
| 400 | INVALID_CHECKS |
A checks value names a record we don’t check |
Every other status, such as 401 for a bad key or 429 at your rate limit, is on Errors.
Test keys
A test key (eva_test_) gets the fixed report above for example.com, with livemode set to false, and it is not charged. Any other domain is refused with 403 LIVE_KEY_REQUIRED. See Sandbox.
From an AI app
The MCP tool audit_domain_authentication returns the same report at the same price. Its arguments are domain and an optional checks. See the MCP server page for connecting an app.