Email authentication
/api/v1/mailhealth-checkPacketFlo Mail Health Check API
MX, SPF, DMARC, DKIM, and blacklist status for a domain in one pass, with a plain verdict.
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain to check. |
Example request
curl "https://packetflo.io/api/v1/mailhealth-check?domain=example.com&api_key=YOUR_API_KEY"
Example response
{ "ok": true, "data": { "domain": "example.com", "verdict": { "status": "critical", "headline": "1 problem found", "summary": "Trouble with: Blacklist Status." }, "checks": [ { "id": "mx", "label": "Mail Servers (MX)", "status": "ok", "summary": "4 mail servers, lowest priority mxa.example.net", "details": { "hosts": [ { "priority": 5, "exchange": "mxa.example.net", "ip": "172.65.169.99", "provider": null }, { "priority": 5, "exchange": "mxb.example.net", "ip": "172.65.65.66", "provider": null }, { "priority": 10, "exchange": "mxc.example.net", "ip": "141.101.90.40", "provider": null }, { "priority": 10, "exchange": "mxd.example.net", "ip": "172.65.64.105", "provider": null } ], "total": 4, "nullMx": false } }, { "id": "spf", "label": "SPF Record", "status": "ok", "summary": "SPF record found with 9 mechanisms.", "details": { "record": "v=spf1 ip4:199.15.212.0/22 include:_spf.example.com -all", "recordCount": 1, "mechanismCount": 9 } }, { "id": "dmarc", "label": "DMARC Policy", "status": "ok", "summary": "Policy is \"reject\" — failing mail is rejected.", "details": { "record": "v=DMARC1; p=reject; pct=100; rua=mailto:[email protected]", "policy": "reject" } }, { "id": "dkim", "label": "DKIM Signing", "status": "ok", "summary": "DKIM key published under selector \"s1\" (and 1 more).", "details": { "selectorsFound": ["s1", "k1"] } }, { "id": "blacklist", "label": "Blacklist Status", "status": "critical", "summary": "Listed: 172.65.169.99 on Spamhaus ZEN.", "details": { "checkedIps": 4, "listedIps": 1, "cleanIps": 3, "results": [ { "ip": "172.65.169.99", "listed": true, "listedOn": ["Spamhaus ZEN"] }, { "ip": "172.65.65.66", "listed": false, "listedOn": [] }, { "ip": "141.101.90.40", "listed": false, "listedOn": [] }, { "ip": "172.65.64.105", "listed": false, "listedOn": [] } ] } } ] }, "meta": { "tool": "mailhealth-check", "version": "v1" } }
Reading the result
verdict.status summarizes ok, warning or critical findings. Read individual checks to understand what needs attention; a warning is not an API failure.
Response fields
| Field | What it tells you |
|---|---|
verdict | Summary status, headline and explanation. |
checks | Checks for mx, spf, dmarc, dkim and blacklist, each with status, summary and details. |
| MX / SPF / DMARC details | Mail hosts and null-MX intent, SPF record counts and mechanisms, and the published DMARC policy. |
| DKIM / blacklist details | Known selectors found and IPv4 MX blocklist findings. Zero observed listings does not guarantee every provider responded. |
Scope and limits
Combines DNS-based checks without sending email or testing mailbox delivery. DKIM checks only common selectors; custom selectors can be missed. A null MX can intentionally declare that a domain accepts no mail. DNS failures can appear as missing configuration.
Authentication and errors
Send your key in the x-api-key header, or the supported api_key query parameter. Each request uses 5 credits from the key's shared 300-credit rolling 24-hour budget. Credits are charged before parameter validation. Successful responses and quota errors include usage headers; GET and OPTIONS support CORS.
| API status | Meaning |
|---|---|
200 | The diagnostic returned a result in data, with ok: true and version information in meta. Read the diagnostic fields to determine the target's condition. |
400 | Invalid or blocked input, or a lookup/check failure that could not be returned as a diagnostic result. Read error for details. |
401 | Missing, invalid or revoked API key. |
429 | The request would exceed the key's available credit budget. |