Analyze Email Headers for Threats with One API Call

The endpoint

InboxWatch exposes an analysis endpoint at POST https://inboxwatch.ai/api/mcp/analyze. It accepts email header fields as JSON and returns a structured threat assessment. An API key is required. Sign up at inboxwatch.ai/check (15 free scans, then $0.10/scan), then create a key at Settings.

The endpoint was designed for the Model Context Protocol (MCP), which means any AI agent that supports tool calling can use it natively. It also works as a standard REST API from any language or platform.

Quick start with curl

Here is a minimal example. Send a POST request with the from,subject, and authenticationResults fields:

curl -X POST https://inboxwatch.ai/api/mcp/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "from": "CEO John Smith <john@g00gle.com>",
    "replyTo": "john.smith.ceo@gmail.com",
    "subject": "Urgent wire transfer needed",
    "authenticationResults": "spf=fail; dkim=none; dmarc=fail",
    "recipientDomain": "yourcompany.com"
  }'

The only required field is from. Every additional field you include improves detection accuracy. The full list of accepted fields:

• from (required) - The From header, including display name if available
• replyTo - The Reply-To header, if it differs from the From address
• subject - Subject line for BEC pattern detection
• messageId - Message-ID header for format analysis
• authenticationResults - The Authentication-Results header containing SPF, DKIM, and DMARC results
• receivedSpf - The Received-SPF header
• dmarcResult - DMARC result if available separately
• received - Array of Received headers in order
• xOriginatingIp - The X-Originating-IP header
• recipientDomain - The recipient's domain for domain spoofing detection

Sample response

The API returns a JSON object with the threat score, threat level, a human-readable verdict, authentication results, and an array of specific threat indicators:

{
  "threatScore": 85,
  "threatLevel": "critical",
  "verdict": "HIGH RISK: 2 critical threat indicator(s) detected. This email shows strong signs of phishing or BEC.",
  "authentication": {
    "spf": "fail",
    "dkim": "none",
    "dmarc": "fail",
    "summary": "All authentication checks failed"
  },
  "indicators": [
    {
      "type": "bec_pattern",
      "severity": "critical",
      "description": "Subject contains urgent financial language commonly used in BEC attacks",
      "evidence": "Urgent wire transfer needed"
    },
    {
      "type": "domain_spoofing",
      "severity": "critical",
      "description": "From domain uses lookalike characters to impersonate a known domain",
      "evidence": "g00gle.com resembles google.com"
    },
    {
      "type": "reply_to_mismatch",
      "severity": "high",
      "description": "Reply-To address differs from From address and uses a free email provider",
      "evidence": "From: g00gle.com, Reply-To: gmail.com"
    }
  ]
}

Rate limit tiers

All API requests require an API key. Sign up at inboxwatch.ai/check, then create a key in your dashboard under Settings. Your account includes 15 free scans, then $0.10 per scan via Stripe. Rate limit: 1,000 requests per minute.

To authenticate, include your API key as a Bearer token in the Authorization header:

curl -X POST https://inboxwatch.ai/api/mcp/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer iw_live_your_api_key_here" \
  -d '{"from": "sender@example.com"}'

Rate limit information is returned in every response via headers:X-RateLimit-Tier, X-RateLimit-Limit,X-RateLimit-Remaining, and X-RateLimit-Reset.

MCP configuration for Claude Desktop

If you use Claude Desktop, you can register InboxWatch as an MCP tool. Add this to yourclaude_desktop_config.json:

{
  "mcpServers": {
    "inboxwatch": {
      "url": "https://inboxwatch.ai/api/mcp"
    }
  }
}

Once configured, Claude can call the inboxwatch_analyze_headerstool directly. Ask it something like "Analyze this email header for threats" and paste the raw headers. Claude will extract the relevant fields and call the API automatically.

Python example

Here is a complete Python example using the requests library:

import requests

API_URL = "https://inboxwatch.ai/api/mcp/analyze"
API_KEY = "iw_live_your_api_key_here"  # optional

headers = {"Content-Type": "application/json"}
if API_KEY:
    headers["Authorization"] = f"Bearer {API_KEY}"

payload = {
    "from": "IT Support <support@yourcompany-reset.com>",
    "subject": "Password expiring in 24 hours",
    "authenticationResults": "spf=none; dkim=none; dmarc=none",
    "recipientDomain": "yourcompany.com"
}

response = requests.post(API_URL, json=payload, headers=headers)
result = response.json()

print(f"Threat Score: {result['threatScore']}/100")
print(f"Level: {result['threatLevel']}")
print(f"Verdict: {result['verdict']}")

for indicator in result.get("indicators", []):
    print(f"  [{indicator['severity']}] {indicator['description']}")

What it detects

The analysis engine checks for multiple threat categories in a single call:

• Domain spoofing - Lookalike domains, homoglyph attacks, typosquatting
• BEC patterns - Urgent financial language, CEO impersonation, wire transfer requests
• Authentication failures - SPF, DKIM, and DMARC results parsed and evaluated together
• Reply-to mismatches - From and Reply-To on different domains, especially free email providers
• Header anomalies - Suspicious Message-ID formats, unusual Received chains, originating IP analysis
• Free provider impersonation - Display names mimicking executives while using consumer email services

Get started

The anonymous tier works immediately with no signup. For higher rate limits, create a free API key in your InboxWatch dashboard under Settings. The key format is iw_live_followed by 48 random characters.

For paid tier access (1,000 requests per minute), sign up with a billing method at inboxwatch.ai/check.

Go further: scan your entire account

The header analysis API checks one email at a time. For full account protection, InboxWatch scans your entire Gmail or Microsoft 365 configuration: 100+ security checks covering forwarding rules, delegates, OAuth apps, sign-in activity, and attack chain correlation. Continuous monitoring every 30 minutes with instant alerts.

Sign up at inboxwatch.ai/check. 15 scans free, then $0.10 each via Stripe.