API Documentation

Integrate our Email Header Analysis engine into your own applications.

On this page

Authentication Rate Limits Endpoints Account Info Webhooks Code Examples

Authentication

All API requests must include your API Key in the Authorization header.

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Accept: application/json

To generate an API Key, go to Settings > Integrations in your dashboard.

Rate Limits

Plan	Limit
Free Tier	Not Available
Pro Plan	Not Available
Business Plan	10,000 requests / month

Endpoints

POSThttps://api.emailsthreatscan.com/api/analyze

Analyzes raw email content for security threats, visual spoofing, and authentication failures.

Request Body

Field	Type	Required	Description
content	string	YES	Raw email (headers + body)
type	string	NO	Defaults to `eml` (text). Use `msg` for OLE.

GET

Get Account Info

GEThttps://api.emailsthreatscan.com/api/account

Retrieves account details, current plan usage, remaining credits, and reset date.

Response Example

{
  "account": {
    "email": "[email protected]",
    "plan": "Business"
  },
  "usage": {
    "used": 145,
    "limit": 10000,
    "remaining": 9855,
    "reset_date": "2026-03-01T00:00:00+00:00"
  },
  "limits": {
    "total_monthly": 10000,
    "web_monthly": 5000,
    "api_monthly": 10000
  }
}

⚡

Webhooks

Webhooks deliver real-time notifications to your server when threats are detected in your monitored mailboxes. Configure webhooks from Settings > Integrations in your dashboard.

Supported Events

Event	Description
threat.detected	Fired when an email is flagged as a threat (phishing, spam, BEC, etc.)

JSON Payload Format

{
  "event": "threat.detected",
  "timestamp": "2026-02-22T12:00:00+00:00",
  "data": {
    "mailbox": "[email protected]",
    "subject": "Urgent: Wire Transfer Required",
    "from": "[email protected]",
    "verdict": "Malicious",
    "score": 15,
    "categories": ["phishing", "bec"],
    "actions_taken": "moved_to_junk"
  }
}

Field	Type	Description
event	string	The event type (e.g. `threat.detected`)
timestamp	string	ISO 8601 timestamp of when the event occurred
data.mailbox	string	The monitored mailbox email address
data.subject	string	Subject line of the flagged email
data.from	string	Sender email address
data.verdict	string	AI verdict (e.g. `Malicious`, `Suspicious`)
data.score	integer	Security score (0–100, lower = more dangerous)
data.categories	string[]	Threat categories (e.g. `phishing`, `bec`, `spam`)
data.actions_taken	string\|null	Auto-action applied (e.g. `moved_to_junk`, `deleted`, or `null`)

Delivery Formats

Choose the format that matches your integration. The payload is automatically reformatted for each platform.

JSON

Custom endpoints

Discord

Rich embeds

Slack

Block Kit

Teams

Adaptive Cards

Security & Verification

✓

HMAC Signing — Each webhook includes an X-Signature header containing an HMAC-SHA256 hash of the payload, signed with your webhook secret. Use this to verify authenticity.

⚠

Auto-Disable — Webhooks are automatically disabled after 10 consecutive delivery failures. Re-enable from your dashboard after fixing the endpoint.

ℹ

Scoping — Webhooks can be scoped to specific mailboxes or organizations. Configure which mailboxes trigger each webhook from your dashboard.

Verify Signature (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
const isValid = verifyWebhook(
  rawBody,                       // raw body string
  req.headers['x-signature'],    // signature header
  'YOUR_WEBHOOK_SECRET'          // from dashboard
);

Code Examples

Get Account Info

cURL

curl -X GET https://api.emailsthreatscan.com/api/account \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Python (Requests)

import requests

url = "https://api.emailsthreatscan.com/api/account"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Analyze Email

cURL

curl -X POST https://api.emailsthreatscan.com/api/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "content": "From: [email protected]\r\nReceived: from bad.com..."
  }'

Python (Requests)

import requests

url = "https://api.emailsthreatscan.com/api/analyze"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "content": "From: [email protected]..."
}

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

Node.js (Axios)

const axios = require('axios');

async function analyzeEmail() {
  try {
    const response = await axios.post('https://api.emailsthreatscan.com/api/analyze', {
      content: 'From: [email protected]...'
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
}

analyzeEmail();