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. Anonymous callers get 10 requests per minute per IP — enough for experimentation or low-volume AI-agent use. For production traffic, sign up at inboxwatch.ai/check (15 free scans, then $0.10/scan) and create an API key at Settings to unlock 1,000 req/min.

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

Anonymous requests are allowed at 10 per minute per IP — perfect for quick tests, playground demos, and low-volume use by AI agents. For production traffic, sign up at inboxwatch.ai/check, create a key in your dashboard under Settings, and send it as a Bearer token to unlock 1,000 requests per minute. The first 15 scans are free; after that it's $0.10 per scan via Stripe.

Authenticated requests pass the key as a Bearer token in the Authorization header. Anonymous callers can simply omit the 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"

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

Sign up at inboxwatch.ai/check and create an API key in your dashboard under Settings. The key format is iw_live_followed by 48 random characters. Rate limit: 1,000 requests per minute.

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: 118+ 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.