Docs menu

Email header analyzer

Paste a message's headers to see every hop, the delays between them and whether SPF, DKIM and DMARC passed.

POST /v1/headers

Price
Free; any API key works and nothing is charged. What you paste is processed in memory and never stored.
Cache
Never cached; every call runs again.
MCP tool
analyze_email_headers

Run it in the browser

Request body

Request body fields
NameTypeDescription
headers (required)stringThe message headers, copied with "Show original" or "View source". A whole message works too; only the headers are read.

Response

Response fields
NameTypeDescription
tool (required)string
target (required)string
status (required)"ok" | "partial" | "error"
fetched_atstring
cachedboolean
credits_usedintegerCredits this call took from your balance. 0 for free tools, for a replay of an earlier call, and for a free check run on the website without signing in
summary (required)string
scoreinteger or null
findingsarray of object
credits_remaining (required)integerYour balance after this call. It can be below zero after a refund; free tools still work then
data (required)objectThis tool's result
data.header_count (required)integer
data.received_count (required)integer
data.hops (required)array of object
data.hops.index (required)integer
data.hops.from_helo (required)string or null
data.hops.from_rdns (required)string or null
data.hops.from_ip (required)string or null
data.hops.ip_scope (required)"public" | "private" | "loopback" | "link_local" | "cgnat" | "reserved" | "documentation" or null
data.hops.by_host (required)string or null
data.hops.protocol (required)string or null
data.hops.tls (required)boolean or null
data.hops.queue_id (required)string or null
data.hops.received_at (required)string or null
data.hops.delay_s (required)integer or null
data.hops.clock_skew (required)boolean
data.hops.largest_delay (required)boolean
data.hops.boundary (required)boolean
data.hops.networkobject or null
data.total_transit_s (required)integer or null
data.auth_results (required)array of object
data.auth_results.authserv_id (required)string
data.auth_results.trusted (required)boolean
data.auth_results.spf (required)object or null
data.auth_results.dkim (required)array of object
data.auth_results.dmarc (required)object or null
data.auth_results.arc (required)object or null
data.auth_results.other (required)array of object
data.alignment (required)object
data.alignment.from_domains (required)array of string
data.alignment.return_path_domain (required)string or null
data.alignment.spf_aligned (required)boolean or null
data.alignment.dkim_domains_claimed (required)array of string
data.alignment.dkim_aligned_pass (required)boolean or null
data.arc_instances (required)integer
data.arc_cv (required)array of string
data.message_id_domain (required)string or null
data.sending_software (required)string or null
data.unsubscribe (required)object
data.spam (required)array of object
data.public_ips (required)array of string
data.verdict (required)"dmarc_pass" | "dmarc_fail" | "no_dmarc" | "unknown"

Errors

  • 400 Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
  • 401 Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
  • 403 Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
  • 429 Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
  • 500 Unexpected error (`internal_error`)

Example

curl

curl
curl -X POST "https://api.dnssuper.com/v1/headers" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Python

Python (httpx)
import os

import httpx

client = httpx.Client(
    base_url="https://api.dnssuper.com",
    headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"},
    timeout=60,
)
response = client.post("/v1/headers", json={})
response.raise_for_status()
result = response.json()
print(result["summary"], result["credits_used"])

TypeScript

TypeScript (fetch)
const response = await fetch("https://api.dnssuper.com/v1/headers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result.summary, result.credits_used);
Example response
Example response
{
  "tool": "email-header-analyzer",
  "target": "",
  "status": "ok",
  "fetched_at": "2026-11-14T10:00:00Z",
  "cached": false,
  "credits_used": 0,
  "summary": "DMARC passed: the receiver authenticated this message as coming from example.com. It took 3 hops in 3 seconds.",
  "findings": [
    {
      "id": "email_headers.dmarc_pass",
      "severity": "pass",
      "title": "The message passed DMARC",
      "detail": "mx.example.net: example.com",
      "fix": "Nothing to do."
    }
  ],
  "data": {
    "header_count": 15,
    "received_count": 3,
    "hops": [
      {
        "index": 0,
        "from_helo": "app.example.com",
        "from_rdns": "app.example.com",
        "from_ip": "198.51.100.10",
        "ip_scope": "documentation",
        "by_host": "mail-out.example.com",
        "protocol": "ESMTPS",
        "tls": true,
        "queue_id": "4XyZ1q2w3e",
        "received_at": "2026-11-14T17:00:01Z",
        "clock_skew": false,
        "largest_delay": false,
        "boundary": false,
        "network": {
          "asn": 64497,
          "name": "EXEMPLE-RESEAU",
          "country": "FR"
        }
      },
      {
        "index": 1,
        "from_helo": "mail-out.example.com",
        "from_rdns": "mail-out.example.com",
        "from_ip": "192.0.2.25",
        "ip_scope": "documentation",
        "by_host": "mx.example.net",
        "protocol": "ESMTPS",
        "tls": true,
        "queue_id": "a1b2c3d4e5.12.2026.11.14.09.00.03",
        "received_at": "2026-11-14T17:00:03Z",
        "delay_s": 2,
        "clock_skew": false,
        "largest_delay": true,
        "boundary": true,
        "network": {
          "asn": 64496,
          "name": "EXAMPLE-NET",
          "country": "NL"
        }
      },
      {
        "index": 2,
        "by_host": "2002:a05:6a10:1234:b0:5f1:aaaa:bbbb",
        "protocol": "SMTP",
        "tls": false,
        "queue_id": "x12csp123456pxa",
        "received_at": "2026-11-14T17:00:04Z",
        "delay_s": 1,
        "clock_skew": false,
        "largest_delay": false,
        "boundary": false
      }
    ],
    "total_transit_s": 3,
    "auth_results": [
      {
        "authserv_id": "mx.example.net",
        "trusted": true,
        "spf": {
          "result": "pass",
          "domain": "example.com"
        },
        "dkim": [
          {
            "result": "pass",
            "domain": "example.com",
            "selector": "s1"
          }
        ],
        "dmarc": {
          "result": "pass",
          "domain": "example.com"
        },
        "other": []
      }
    ],
    "alignment": {
      "from_domains": [
        "example.com"
      ],
      "return_path_domain": "example.com",
      "spf_aligned": true,
      "dkim_domains_claimed": [
        "example.com"
      ],
      "dkim_aligned_pass": true
    },
    "arc_instances": 0,
    "arc_cv": [],
    "message_id_domain": "app.example.com",
    "sending_software": "Example Mailer 4.2",
    "unsubscribe": {
      "present": false,
      "https": false,
      "mailto": false,
      "one_click": false
    },
    "spam": [],
    "public_ips": [],
    "verdict": "dmarc_pass"
  },
  "credits_remaining": 498
}

MCP

MCP tool call
{
  "tool": "analyze_email_headers",
  "arguments": {}
}
Compact MCP output
DMARC passed: the receiver authenticated this message as coming from example.com. It took 3 hops in 3 seconds.
Verdict: DMARC pass (receiver mx.example.net)
Path: 3 hops in 3 seconds; entered at mx.example.net
SPF: pass for example.com (aligned) | DKIM: pass for example.com (aligned) | DMARC: pass
1 check passed
Free | checked 2026-11-14 10:00 UTC