AI Verdict

AI-enhanced phishing analysis that combines heuristic checks with a large language model to provide detailed risk assessment, natural language findings, and recommended response actions.

POST/api/v1/phishing/analyze/ai

Authentication

API key with phishing:read permission

Credits

10 credits per request

Plans

Starter, Professional, Enterprise

Graceful Degradation

If the AI model is temporarily unavailable, the endpoint returns heuristic analysis results with ai_verdict: null and 0 credits are charged. Your integration should always check whether ai_verdict is present before accessing its fields.

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": "eml",
  "content": "Received: from mail.example.com (mail.example.com [93.184.216.34])\n  by mx.google.com with ESMTPS id a1-2020...\nFrom: security@paypa1.com\nTo: user@company.com\nSubject: Action Required: Unusual Sign-In Activity\nDate: Thu, 19 Mar 2026 14:22:05 +0000\nMessage-ID: <def456@mail.example.com>\nContent-Type: text/html; charset=UTF-8\nAuthentication-Results: mx.google.com;\n  dkim=fail header.d=paypa1.com;\n  spf=fail smtp.mailfrom=paypa1.com;\n  dmarc=fail header.from=paypa1.com\n\n<html><body>\n<p>Dear Customer,</p>\n<p>We detected unusual activity on your account. Please <a href=\"https://paypa1-secure.example.net/verify\">verify your identity</a> within 24 hours or your account will be suspended.</p>\n<p>PayPal Security Team</p>\n</body></html>",
  "options": {
    "include_iocs": true,
    "include_body_analysis": true,
    "include_homoglyph_check": true,
    "include_link_analysis": true,
    "include_attachment_analysis": true
  }
}

Response

The response includes all fields from the /phishing/analyze endpoint, plus an additional ai_verdict object with AI-generated analysis.

FieldTypeDescription
ai_verdict.risk_levelstringOverall risk assessment: low, medium, high, or critical
ai_verdict.confidence_scorenumberConfidence in the assessment, from 0.0 to 1.0
ai_verdict.findingsstring[]Natural language explanations of each risk signal detected
ai_verdict.recommended_actionsstring[]Suggested remediation steps for the security team

Example Response

{
  "success": true,
  "data": {
    "verdict": "phishing",
    "score": 94,
    "summary": "High-confidence phishing email impersonating PayPal with failed authentication, homoglyph domain, and credential harvesting link.",
    "authentication": {
      "spf": {
        "result": "fail",
        "detail": "SPF record does not authorize 93.184.216.34 to send for paypa1.com"
      },
      "dkim": {
        "result": "fail",
        "detail": "DKIM signature verification failed for domain paypa1.com"
      },
      "dmarc": {
        "result": "fail",
        "policy": "reject",
        "detail": "Message failed DMARC evaluation for paypa1.com"
      }
    },
    "indicators": [
      {
        "type": "auth_failure",
        "severity": "high",
        "description": "All email authentication mechanisms (SPF, DKIM, DMARC) failed"
      },
      {
        "type": "homoglyph",
        "severity": "high",
        "description": "Domain 'paypa1.com' uses digit '1' in place of letter 'l' (homoglyph of 'paypal.com')"
      },
      {
        "type": "suspicious_link",
        "severity": "high",
        "description": "Link destination 'paypa1-secure.example.net' does not match sender domain and appears to be a credential phishing page"
      },
      {
        "type": "urgency",
        "severity": "medium",
        "description": "Body contains urgency language: 'within 24 hours', 'account will be suspended'"
      },
      {
        "type": "brand_impersonation",
        "severity": "high",
        "description": "Email impersonates PayPal with lookalike domain and branding"
      }
    ],
    "iocs": {
      "domains": ["paypa1.com", "paypa1-secure.example.net", "mail.example.com"],
      "ips": ["93.184.216.34"],
      "emails": ["security@paypa1.com"],
      "urls": ["https://paypa1-secure.example.net/verify"]
    },
    "ai_verdict": {
      "risk_level": "critical",
      "confidence_score": 0.97,
      "findings": [
        "The sender domain 'paypa1.com' is a homoglyph of 'paypal.com', using the digit '1' to replace the letter 'l'. This is a well-known brand impersonation technique.",
        "All three email authentication mechanisms (SPF, DKIM, DMARC) have failed, confirming the sender is not authorized to send on behalf of this domain.",
        "The email body contains a credential harvesting link pointing to 'paypa1-secure.example.net', which is an unrelated domain designed to appear legitimate.",
        "The message uses social engineering tactics including urgency ('24 hours'), fear of loss ('account will be suspended'), and authority impersonation ('PayPal Security Team').",
        "The HTML structure is minimal and lacks legitimate PayPal email formatting, footers, and unsubscribe links typically present in authentic communications."
      ],
      "recommended_actions": [
        "Block sender domain 'paypa1.com' at the email gateway",
        "Add 'paypa1-secure.example.net' to URL blocklist",
        "Alert the recipient and advise not to click any links",
        "Report the domain to the registrar for abuse",
        "Submit the phishing URL to Google Safe Browsing and PhishTank"
      ]
    },
    "headers_analyzed": 9,
    "processing_time_ms": 2840
  },
  "credits_used": 10,
  "credits_remaining": 490
}

Code Examples

cURL

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

Python

import requests

url = "https://dfir-lab.ch/api/v1/phishing/analyze/ai"
headers = {
    "Authorization": "Bearer sk-dfir-your-key-here",
    "Content-Type": "application/json",
}
payload = {
    "input_type": "eml",
    "content": open("suspicious_email.eml").read(),
    "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']} (score: {data['data']['score']}/100)")

# AI-specific results
ai = data["data"]["ai_verdict"]
if ai:
    print(f"AI Risk Level: {ai['risk_level']}")
    print(f"AI Confidence: {ai['confidence_score']:.0%}")
    print("\nAI Findings:")
    for finding in ai["findings"]:
        print(f"  - {finding}")
    print("\nRecommended Actions:")
    for action in ai["recommended_actions"]:
        print(f"  - {action}")
else:
    print("AI analysis unavailable — heuristic results returned (0 credits charged)")

TypeScript

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

interface AIVerdict {
  risk_level: "low" | "medium" | "high" | "critical";
  confidence_score: number;
  findings: string[];
  recommended_actions: string[];
}

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}`);

const ai: AIVerdict | null = data.ai_verdict;
if (ai) {
  console.log(`AI Risk: ${ai.risk_level} (confidence: ${(ai.confidence_score * 100).toFixed(0)}%)`);
  ai.findings.forEach((f: string) => console.log(`  Finding: ${f}`));
  ai.recommended_actions.forEach((a: string) => console.log(`  Action: ${a}`));
} else {
  console.log("AI analysis unavailable — heuristic results only (0 credits charged)");
}