# Email header analyzer API

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`

The delivery path, authentication results and alignment read from pasted email headers. Free; any API key works and nothing is charged. What you paste is processed in memory and never stored. Never cached; every call runs again.

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `headers` | string | yes | The message headers, copied with "Show original" or "View source". A whole message works too; only the headers are read. |

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes |  |
| `target` | string | yes |  |
| `status` | "ok" | "partial" | "error" | yes |  |
| `fetched_at` | string | no |  |
| `cached` | boolean | no |  |
| `credits_used` | integer | no | Credits 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` | string | yes |  |
| `score` | integer or null | no |  |
| `findings` | array of object | no |  |
| `credits_remaining` | integer | yes | Your balance after this call. It can be below zero after a refund; free tools still work then |
| `data` | object | yes | This tool's result |
| `data.header_count` | integer | yes |  |
| `data.received_count` | integer | yes |  |
| `data.hops` | array of object | yes |  |
| `data.hops.index` | integer | yes |  |
| `data.hops.from_helo` | string or null | yes |  |
| `data.hops.from_rdns` | string or null | yes |  |
| `data.hops.from_ip` | string or null | yes |  |
| `data.hops.ip_scope` | "public" | "private" | "loopback" | "link_local" | "cgnat" | "reserved" | "documentation" or null | yes |  |
| `data.hops.by_host` | string or null | yes |  |
| `data.hops.protocol` | string or null | yes |  |
| `data.hops.tls` | boolean or null | yes |  |
| `data.hops.queue_id` | string or null | yes |  |
| `data.hops.received_at` | string or null | yes |  |
| `data.hops.delay_s` | integer or null | yes |  |
| `data.hops.clock_skew` | boolean | yes |  |
| `data.hops.largest_delay` | boolean | yes |  |
| `data.hops.boundary` | boolean | yes |  |
| `data.hops.network` | object or null | no |  |
| `data.total_transit_s` | integer or null | yes |  |
| `data.auth_results` | array of object | yes |  |
| `data.auth_results.authserv_id` | string | yes |  |
| `data.auth_results.trusted` | boolean | yes |  |
| `data.auth_results.spf` | object or null | yes |  |
| `data.auth_results.dkim` | array of object | yes |  |
| `data.auth_results.dmarc` | object or null | yes |  |
| `data.auth_results.arc` | object or null | yes |  |
| `data.auth_results.other` | array of object | yes |  |
| `data.alignment` | object | yes |  |
| `data.alignment.from_domains` | array of string | yes |  |
| `data.alignment.return_path_domain` | string or null | yes |  |
| `data.alignment.spf_aligned` | boolean or null | yes |  |
| `data.alignment.dkim_domains_claimed` | array of string | yes |  |
| `data.alignment.dkim_aligned_pass` | boolean or null | yes |  |
| `data.arc_instances` | integer | yes |  |
| `data.arc_cv` | array of string | yes |  |
| `data.message_id_domain` | string or null | yes |  |
| `data.sending_software` | string or null | yes |  |
| `data.unsubscribe` | object | yes |  |
| `data.spam` | array of object | yes |  |
| `data.public_ips` | array of string | yes |  |
| `data.verdict` | "dmarc_pass" | "dmarc_fail" | "no_dmarc" | "unknown" | yes |  |

## 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

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

```python
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"])
```

```ts
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:

```json
{
  "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

```json
{
  "tool": "analyze_email_headers",
  "arguments": {}
}
```

```text
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
```
