Analyze Email

Heuristic analysis of email headers for phishing indicators. Returns a verdict, confidence score, authentication results, and extracted IOCs.

POST/api/v1/phishing/analyze

Authentication

API key with phishing:read permission

Credits

1 credit per request

Plans

Available on all plans

Request Body

FieldTypeRequiredDescription
input_type"headers" | "eml" | "raw"YesFormat of the email content. Use "headers" for raw header text, "eml" for a full .eml file, or "raw" for unstructured email source.
contentstringYesThe email content to analyze. Maximum size 5 MB.
optionsobjectNoOptional analysis toggles. All default to false if omitted.
options.include_iocsbooleanNoExtract IOCs (domains, IPs, emails, URLs) from the email.
options.include_body_analysisbooleanNoAnalyze email body text for phishing language patterns.
options.include_homoglyph_checkbooleanNoDetect homoglyph/typosquat domains that impersonate known brands.
options.include_link_analysisbooleanNoInspect URLs in the email body for suspicious patterns.
options.include_attachment_analysisbooleanNoAnalyze attachment metadata (file names, types, sizes) for risk signals.

Example Request Body

{
  "input_type": "headers",
  "content": "Received: from mail.example.com (mail.example.com [93.184.216.34])\n  by mx.google.com with ESMTPS id a1-2020...\nFrom: support@examp1e-bank.com\nTo: victim@company.com\nSubject: Urgent: Verify Your Account\nDate: Thu, 19 Mar 2026 08:45:12 +0000\nMessage-ID: <abc123@mail.example.com>\nAuthentication-Results: mx.google.com;\n  dkim=fail header.d=examp1e-bank.com;\n  spf=softfail smtp.mailfrom=examp1e-bank.com;\n  dmarc=fail header.from=examp1e-bank.com",
  "options": {
    "include_iocs": true,
    "include_body_analysis": true,
    "include_homoglyph_check": true,
    "include_link_analysis": true,
    "include_attachment_analysis": true
  }
}

Response

A successful request returns a JSON object with the analysis results. The verdict field is one of clean, suspicious, or phishing. The score ranges from 0 (safe) to 100 (confirmed phishing).

{
  "success": true,
  "data": {
    "verdict": "phishing",
    "score": 87,
    "summary": "High-confidence phishing email with multiple failed authentication checks and suspicious domain patterns.",
    "authentication": {
      "spf": {
        "result": "softfail",
        "detail": "SPF record does not authorize 93.184.216.34 to send for examp1e-bank.com"
      },
      "dkim": {
        "result": "fail",
        "detail": "DKIM signature verification failed for domain examp1e-bank.com"
      },
      "dmarc": {
        "result": "fail",
        "policy": "reject",
        "detail": "Message failed DMARC evaluation for examp1e-bank.com"
      }
    },
    "indicators": [
      {
        "type": "auth_failure",
        "severity": "high",
        "description": "SPF, DKIM, and DMARC all failed — sender is not authorized"
      },
      {
        "type": "homoglyph",
        "severity": "high",
        "description": "Domain 'examp1e-bank.com' uses digit '1' in place of letter 'l' (homoglyph of 'example-bank.com')"
      },
      {
        "type": "urgency",
        "severity": "medium",
        "description": "Subject line contains urgency language: 'Urgent: Verify Your Account'"
      },
      {
        "type": "sender_mismatch",
        "severity": "medium",
        "description": "Envelope sender domain does not match common known brands"
      }
    ],
    "iocs": {
      "domains": ["examp1e-bank.com", "mail.example.com"],
      "ips": ["93.184.216.34"],
      "emails": ["support@examp1e-bank.com"],
      "urls": []
    },
    "headers_analyzed": 8,
    "processing_time_ms": 142
  },
  "credits_used": 1,
  "credits_remaining": 499
}

Code Examples

cURL

curl -X POST https://dfir-lab.ch/api/v1/phishing/analyze \
  -H "Authorization: Bearer sk-dfir-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "input_type": "headers",
    "content": "Received: from mail.example.com ...",
    "options": {
      "include_iocs": true,
      "include_homoglyph_check": true
    }
  }'

Python

import requests

url = "https://dfir-lab.ch/api/v1/phishing/analyze"
headers = {
    "Authorization": "Bearer sk-dfir-your-key-here",
    "Content-Type": "application/json",
}
payload = {
    "input_type": "headers",
    "content": "Received: from mail.example.com ...",
    "options": {
        "include_iocs": True,
        "include_body_analysis": True,
        "include_homoglyph_check": True,
        "include_link_analysis": True,
        "include_attachment_analysis": True,
    },
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(f"Verdict: {data['data']['verdict']}")
print(f"Score: {data['data']['score']}/100")

for indicator in data["data"]["indicators"]:
    print(f"  [{indicator['severity'].upper()}] {indicator['description']}")

TypeScript

const response = await fetch("https://dfir-lab.ch/api/v1/phishing/analyze", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-dfir-your-key-here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input_type: "headers",
    content: "Received: from mail.example.com ...",
    options: {
      include_iocs: true,
      include_body_analysis: true,
      include_homoglyph_check: true,
      include_link_analysis: true,
      include_attachment_analysis: true,
    },
  }),
});

const { data, credits_used, credits_remaining } = await response.json();

console.log(`Verdict: ${data.verdict} (score: ${data.score}/100)`);
console.log(`Credits used: ${credits_used}, remaining: ${credits_remaining}`);

for (const indicator of data.indicators) {
  console.log(`  [${indicator.severity.toUpperCase()}] ${indicator.description}`);
}