Tools

Free public tools for email header analysis and domain health checks. These endpoints do not require authentication and are rate-limited per IP (header analyzer: 20 requests/minute; domain check: 30 requests/minute).

Header Analyzer

POST /v1/public/tools/header-analyzer

Parse and analyze raw email headers to trace the delivery path, extract authentication results, identify the sending infrastructure, and detect anomalies. IP enrichment is applied to the first 20 IP-bearing Received hops.

Authentication

None required (public endpoint).

Request Body

{
  "headers": "Received: from mail-wr1-f41.google.com (209.85.221.41) by mx.example.com with ESMTPS; Sun, 13 Apr 2026 10:00:00 +0000\r\nAuthentication-Results: mx.example.com; spf=pass smtp.mailfrom=user@gmail.com\r\nDKIM-Signature: v=1; a=rsa-sha256; d=gmail.com; s=20230601; ..."
}

Field	Type	Required	Description
`headers`	string	Yes	Raw email headers to analyze, maximum 48 KiB

The complete JSON request body is limited to 64 KiB. Requests exceeding either limit return 413 Payload Too Large.

Response (200)

{
  "data": {
    "received_chain": [
      {
        "from_host": "mail-wr1-f41.google.com",
        "from_ip": "209.85.221.41",
        "by_host": "mx.example.com",
        "protocol": "ESMTPS",
        "timestamp": "2026-04-13T10:00:00Z",
        "delay": "0s",
        "asn": 15169,
        "asn_name": "Google LLC",
        "country": "US",
        "cloud_provider": "Google Cloud",
        "connection_type": "datacenter",
        "threat_score": 0
      }
    ],
    "authentication": {
      "spf_result": "pass",
      "dkim_result": "present",
      "dkim_selector": "20230601",
      "dkim_domain": "gmail.com"
    },
    "infrastructure": {
      "origin_ip": "209.85.221.41",
      "from_domain": "gmail.com",
      "x_mailer": "",
      "user_agent": ""
    },
    "anomalies": []
  },
  "meta": {
    "processing_time_ms": 25
  }
}

Response Fields

Received Chain (per hop)

Field	Type	Description
`from_host`	string	Sending host name
`from_ip`	string	Sending IP address
`by_host`	string	Receiving host name
`protocol`	string	Transfer protocol (SMTP, ESMTP, ESMTPS)
`timestamp`	string	RFC 3339 timestamp from header
`delay`	string	Time delay since previous hop
`asn`	integer	ASN of the sending IP (enriched)
`asn_name`	string	ASN organization name (enriched)
`country`	string	Country code of the sending IP (enriched)
`cloud_provider`	string	Cloud provider if detected (enriched)
`connection_type`	string	Connection type (enriched)
`threat_score`	integer	Threat score of the sending IP (enriched)

Authentication

Field	Type	Description
`spf_result`	string	SPF result (pass, fail, softfail, none)
`dkim_result`	string	DKIM status (present, absent)
`dkim_selector`	string	DKIM selector used
`dkim_domain`	string	DKIM signing domain
`dmarc_result`	string	DMARC result if found

Infrastructure

Field	Type	Description
`origin_ip`	string	Originating IP (first hop with an IP)
`from_domain`	string	Sending domain
`x_mailer`	string	X-Mailer header value
`user_agent`	string	User-Agent header value

Anomalies

Array of detected anomalies (strings). Examples:

"Negative time delay between hops -- possible forged Received header"

Privacy-bounded intelligence contribution

Successful analyses contribute a privacy-bounded observation to the intelligence pipeline when the database is available. The stored record has a 30-day retention boundary and contains only deduplicated public IPs extracted from Received headers plus aggregate hop counts, authentication result categories, and stable anomaly codes. Raw headers, email addresses, subjects, hostnames, mailer values, and user-agent values are never stored or logged; private, reserved, and documentation IPs are excluded. User-submitted header data is not treated as an authoritative honeypot or blocklist signal.

Domain Check

GET /v1/public/tools/domain-check/{domain}

Quick public domain health check. Combines MX, SPF, DKIM, DMARC, MTA-STS, and BIMI validation into a single grade. Similar to the /v1/email/domain/{domain}/dns endpoint but designed as a free tool without requiring authentication.

Authentication

None required (public endpoint).

Path Parameters

Parameter	Type	Required	Description
`domain`	string	Yes	Public DNS hostname with at least two valid labels; IP literals, underscores, empty labels, and single-label names are rejected

The complete check has a five-second deadline. All MX, SPF, DKIM, MTA-STS, and BIMI work shares a 32-lookup request budget and the process-wide DNS concurrency bound. Successful results are cached in a bounded one-hour cache. The public route is limited to 30 requests per minute per client IP.

Response (200)

{
  "data": {
    "domain": "example.com",
    "grade": "B",
    "score": 80,
    "mx": {
      "records": ["mx1.example.com", "mx2.example.com"],
      "is_valid": true
    },
    "spf": {
      "raw": "v=spf1 include:_spf.google.com ~all",
      "mechanisms": ["include:_spf.google.com", "~all"],
      "all_qualifier": "~",
      "is_valid": true,
      "is_permissive": false,
      "dns_lookup_count": 3,
      "exceeds_lookups": false
    },
    "dkim": [
      {
        "selector": "google",
        "found": true,
        "key_type": "rsa",
        "key_bits": 2048,
        "is_valid": true
      }
    ],
    "dmarc": {
      "raw": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com",
      "version": "DMARC1",
      "policy": "quarantine",
      "subdomain_policy": "quarantine",
      "effective_policy": "quarantine",
      "percentage": 100,
      "aggregate_report_uris": ["mailto:dmarc@example.com"],
      "dkim_alignment": "r",
      "spf_alignment": "r",
      "report_interval": 86400,
      "record_domain": "example.com",
      "inherited": false,
      "strength_rating": "moderate",
      "is_valid": true
    },
    "mta_sts": {
      "found": true,
      "is_valid": true,
      "version": "STSv1",
      "id": "20260822"
    },
    "bimi": {
      "selector": "default",
      "found": true,
      "is_valid": true,
      "version": "BIMI1",
      "logo_url": "https://example.com/logo.svg"
    },
    "recommendations": [
      "Consider upgrading DMARC policy from quarantine to reject for maximum protection"
    ]
  },
  "meta": {
    "processing_time_ms": 500
  }
}

Response Fields

Field	Type	Description
`domain`	string	The checked domain
`grade`	string	Letter grade (A-F)
`score`	integer	Numeric score (0-100)
`mx`	object	MX record results
`spf`	object	SPF record analysis
`dkim`	array	DKIM records found
`dmarc`	object	DMARC record analysis
`mta_sts`	object	MTA-STS TXT record analysis
`bimi`	object	Default-selector BIMI record analysis
`recommendations`	array	Actionable improvement suggestions

Grading

Grade	Score	Description
A	90-100	Excellent email authentication
B	75-89	Good, minor improvements possible
C	55-74	Moderate risk, missing configurations
D	35-54	Poor, significant gaps
F	0-34	Critical, minimal or no authentication

Telemetry Ingestion

POST /v1/email/telemetry/ingest

Submit email sending telemetry observations from your system. This data feeds into the reputation scoring engine. Maximum 100 observations per request.

Authentication

Required (API key with the administrator-provisioned telemetry_ingest feature). The sending IP must also be in that key's verified monitored-IP pool; unregistered and unverified IPs are rejected.

Request Body

{
  "observations": [
    {
      "ip": "YOUR_VERIFIED_IP",
      "bounce_rate": 0.03,
      "complaint_rate": 0.001,
      "volume_24h": 5000,
      "observed_at": "2026-04-13T10:00:00Z"
    },
    {
      "ip": "YOUR_SECOND_VERIFIED_IP",
      "bounce_rate": 0.15,
      "complaint_rate": 0.005,
      "volume_24h": 800,
      "observed_at": "2026-04-13T10:00:00Z"
    }
  ]
}

Observation Fields

Field	Type	Required	Description
`ip`	string	Yes	Sending IP address
`bounce_rate`	number	No	Bounce rate (0.0 to 1.0)
`complaint_rate`	number	No	Complaint rate (0.0 to 1.0)
`volume_24h`	integer	No	Sending volume in last 24h
`observed_at`	string	No	ISO 8601 timestamp (defaults to now, must be within last 48h)

Response (200)

{
  "data": {
    "accepted": 2,
    "rejected": 0,
    "errors": []
  },
  "meta": {
    "processing_time_ms": 15
  }
}

Response Fields

Field	Type	Description
`accepted`	integer	Number of observations stored
`rejected`	integer	Number of observations rejected
`errors`	array	Error messages for rejected observations

Validation Rules

bounce_rate must be 0.0 to 1.0
complaint_rate must be 0.0 to 1.0
volume_24h must be >= 0
observed_at must be within the last 48 hours and not in the future
Maximum 100 observations per request
Invalid IPs are rejected with an error message
Requests are limited to 120 per minute per API key

Error Responses

400 Bad Request

{
  "data": {
    "error": "headers field is required",
    "code": "MISSING_HEADERS"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

401 Unauthorized (Telemetry only)

{
  "data": {
    "error": "authentication required",
    "code": "AUTH_REQUIRED"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

413 Payload Too Large (Header Analyzer)

{
  "data": {
    "error": "headers field exceeds 48 KiB",
    "code": "HEADERS_TOO_LARGE"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

504 Gateway Timeout (Domain Check)

{
  "data": {
    "error": "domain check exceeded its time limit",
    "code": "DOMAIN_CHECK_TIMEOUT"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

Code Examples

cURL

# Header analysis (no auth needed)
curl -X POST "https://api.limesindex.com/v1/public/tools/header-analyzer" \
  -H "Content-Type: application/json" \
  -d '{"headers": "Received: from mail.example.com (198.51.100.25) by mx.google.com..."}'

# Domain check (no auth needed)
curl -X GET "https://api.limesindex.com/v1/public/tools/domain-check/example.com"

# Telemetry ingestion (auth required)
curl -X POST "https://api.limesindex.com/v1/email/telemetry/ingest" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "observations": [
      {
        "ip": "YOUR_VERIFIED_IP",
        "bounce_rate": 0.03,
        "complaint_rate": 0.001,
        "volume_24h": 5000,
        "observed_at": "2026-04-13T10:00:00Z"
      }
    ]
  }'

Python

import requests

BASE_URL = "https://api.limesindex.com"

# Header analysis (public, no auth)
raw_headers = """Received: from mail.example.com (198.51.100.25) by mx.google.com
    with ESMTPS; Sun, 13 Apr 2026 10:00:00 +0000
Authentication-Results: mx.google.com; spf=pass"""

resp = requests.post(
    f"{BASE_URL}/v1/public/tools/header-analyzer",
    json={"headers": raw_headers}
)
analysis = resp.json()["data"]
for hop in analysis["received_chain"]:
    print(f"Hop: {hop.get('from_ip', '?')} -> {hop.get('by_host', '?')}")
    if hop.get("asn"):
        print(f"  ASN: {hop['asn']} ({hop['asn_name']})")

# Domain check (public, no auth)
resp = requests.get(f"{BASE_URL}/v1/public/tools/domain-check/example.com")
check = resp.json()["data"]
print(f"Grade: {check['grade']} (Score: {check['score']})")
for rec in check["recommendations"]:
    print(f"  - {rec}")

# Telemetry ingestion (auth required)
API_KEY = "YOUR_API_KEY"
resp = requests.post(
    f"{BASE_URL}/v1/email/telemetry/ingest",
    headers={"X-API-Key": API_KEY},
    json={
        "observations": [
            {
                "ip": "YOUR_VERIFIED_IP",
                "bounce_rate": 0.03,
                "complaint_rate": 0.001,
                "volume_24h": 5000
            }
        ]
    }
)
result = resp.json()["data"]
print(f"Accepted: {result['accepted']}, Rejected: {result['rejected']}")

Use Cases

Header forensics: Trace email delivery issues by analyzing Received headers
Domain auditing: Check any domain's email auth setup before sending to it
Telemetry contribution: Share your sending metrics to improve the global reputation model
Onboarding: Validate domain DNS before adding to your platform

Email Domain DNS - Authenticated version with persistence
Email Reputation - IP reputation scoring
Warmup - Warm-up guidance based on telemetry data

Header Analyzer​

Authentication​

Request Body​

Response (200)​

Response Fields​

Received Chain (per hop)​

Authentication​

Infrastructure​

Anomalies​

Privacy-bounded intelligence contribution​

Domain Check​

Authentication​

Path Parameters​

Response (200)​

Response Fields​

Grading​

Telemetry Ingestion​

Authentication​

Request Body​

Observation Fields​

Response (200)​

Response Fields​

Validation Rules​

Error Responses​

400 Bad Request​

401 Unauthorized (Telemetry only)​

413 Payload Too Large (Header Analyzer)​

504 Gateway Timeout (Domain Check)​

Code Examples​

cURL​

Python​

Use Cases​

Related Endpoints​

Header Analyzer

Authentication

Request Body

Response (200)

Response Fields

Received Chain (per hop)

Authentication

Infrastructure

Anomalies

Privacy-bounded intelligence contribution

Domain Check

Authentication

Path Parameters

Response (200)

Response Fields

Grading

Telemetry Ingestion

Authentication

Request Body

Observation Fields

Response (200)

Response Fields

Validation Rules

Error Responses

400 Bad Request

401 Unauthorized (Telemetry only)

413 Payload Too Large (Header Analyzer)

504 Gateway Timeout (Domain Check)

Code Examples

cURL

Python

Use Cases

Related Endpoints