BetterPhish API Documentation

Welcome to the BetterPhish spam analysis API. This API allows you to analyze emails for spam, phishing, and malware in real-time.

Base URL: https://spam.betterphish.io
All API endpoints are relative to this base URL.

Authentication

All API requests require authentication via the X-API-Key header.

HTTP Header 
X-API-Key: bp_your_api_key_here

Get your API key by signing up for free.

Quick Start

Here's a simple example to analyze an email:

cURL 
curl -X POST https://spam.betterphish.io/v1/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bp_your_api_key" \
  -d '{
    "raw_message": "From: spammer@example.com\nTo: victim@example.com\nSubject: You won!\n\nClick here to claim your prize!"
  }'
Python 
import httpx

response = httpx.post(
    "https://spam.betterphish.io/v1/analyze",
    headers={"X-API-Key": "bp_your_api_key"},
    json={"raw_message": open("email.eml").read()}
)

result = response.json()
print(f"Verdict: {result['verdict']}, Score: {result['score']}")

Analyze Email

POST /v1/analyze

Analyze a single email message for spam, phishing, and malware.

Request Body

ParameterTypeDescription
raw_message required string Raw email message (RFC 5322 format)
sender_ip optional string IP address of sending server
mail_from optional string SMTP envelope sender
rcpt_to optional array SMTP envelope recipients

Response

JSON 
{
  "verdict": "SPAM",
  "score": 15.7,
  "threshold": 15.0,
  "action": "reject",
  "is_spam": true,
  "symbols": {
    "BAYES_SPAM": {"score": 5.0, "description": "Bayes spam probability"},
    "PHISHING": {"score": 3.5, "description": "Phishing URL detected"},
    "MISSING_MID": {"score": 2.5, "description": "Missing Message-ID"}
  },
  "urls": ["http://malicious.example.com/prize"],
  "emails": ["spammer@example.com"],
  "message_id": null,
  "analysis_time_ms": 45.2,
  "request_id": "abc123def456"
}

BetterSpam: Anti-Spam Engine

BetterSpam is our proprietary email analysis engine that combines multiple detection techniques to identify spam, phishing, malware, and other email threats with industry-leading accuracy.

Multi-Layer Protection: BetterSpam combines Bayesian classification, heuristic rules, real-time threat intelligence, and machine learning to catch threats that single-technique solutions miss.

Engine Features

Bayesian Classification

Self-learning statistical classifier that adapts to your specific spam patterns. Train with your own data for personalized detection.

DNS Science Integration

Real-time threat intelligence lookups against our DNS Science database covering IPs, domains, and URLs with reputation scoring.

DarkAPI ML Models

Machine learning classification using our DarkAPI models trained on millions of spam, phishing, and malware samples.

SPF/DKIM/DMARC

Full email authentication verification including SPF, DKIM signature validation, and DMARC policy enforcement.

RBL/DNSBL Lookups

Queries against 20+ real-time blocklists including Spamhaus, SURBL, and proprietary threat feeds.

Zero-Day Detection

Anomaly detection and behavioral analysis to catch new threats before they appear in traditional blocklists.

Detection Symbols

BetterSpam returns detailed symbols explaining why an email was flagged. Here are the key symbol categories:

DNS Science Threat Intelligence

SymbolWeightDescription
DNSSCIENCE_BLOCKED 7.0 Sender IP or domain found on DNS Science blocklist
DNSSCIENCE_MALICIOUS 8.0 Very poor reputation score (≤ -50)
DNSSCIENCE_PHISHING 6.0 Known phishing domain or URL detected
DNSSCIENCE_MALWARE 8.0 Known malware distribution host
DNSSCIENCE_C2 10.0 Command & Control server detected
DNSSCIENCE_BOTNET 7.0 Known botnet node

DarkAPI ML Classification

SymbolWeightDescription
DARKAPI_SPAM 5.0 ML model classified as spam (confidence ≥ 70%)
DARKAPI_PHISHING 7.0 ML model classified as phishing (confidence ≥ 75%)
DARKAPI_MALWARE 8.0 ML model classified as malware (confidence ≥ 80%)
DARKAPI_BEC 7.0 Business Email Compromise attempt detected
DARKAPI_ZERO_DAY 6.0 Potential zero-day threat pattern
DARKAPI_URL_THREAT 5.0 URL with high threat score detected
Scoring: Symbol weights are added together. When the total exceeds the threshold (default: 15), the email is marked as spam. The action field in the response indicates the recommended action: no action, add header, rewrite subject, soft reject, or reject.

IOC Threat Feeds

Access threat intelligence extracted from analyzed spam. Available on Pro tier and above.

IOC feeds include malicious IPs, phishing domains, spam URLs, and malware file hashes - all extracted from real spam campaigns.
GET /v1/ioc/feed/{type}

Get threat intelligence feed by IOC type.

Path Parameters

ParameterTypeDescription
type required string IOC type: ip, domain, url, file_hash

Query Parameters

ParameterTypeDescription
category optional string Filter by threat category: spam, phishing, malware, scam
min_confidence optional float Minimum confidence score (0.0-1.0). Default: 0.5
format optional string Output format: json (default), csv, stix
limit optional integer Max results (1-10000). Default: 1000

Response (JSON)

JSON 
{
  "feed_name": "betterphish-domain-phishing",
  "generated_at": "2026-01-18T12:34:56Z",
  "total_entries": 1523,
  "entries": [
    {
      "indicator": "secure-login-verify.com",
      "type": "domain",
      "category": "phishing",
      "confidence": 0.92,
      "first_seen": "2026-01-17T08:12:00Z",
      "last_seen": "2026-01-18T11:45:00Z",
      "hit_count": 47,
      "tags": ["domain", "phishing"]
    }
  ]
}

Response (STIX 2.1)

STIX 2.1 
{
  "type": "bundle",
  "id": "bundle--a1b2c3d4",
  "objects": [
    {
      "type": "indicator",
      "spec_version": "2.1",
      "id": "indicator--abc123",
      "name": "secure-login-verify.com",
      "pattern": "[domain:value = 'secure-login-verify.com']",
      "pattern_type": "stix",
      "indicator_types": ["phishing"],
      "confidence": 92
    }
  ]
}

Create Account

POST /v1/signup

Create a free account and get an API key instantly.

Request Body

ParameterTypeDescription
email required string Your email address
name required string Your name or company name
company optional string Company name

Response

JSON 
{
  "api_key": "bp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "tier": "free",
  "message": "Account created successfully!",
  "next_steps": [
    "Save your API key securely - it won't be shown again",
    "Test the API at https://spam.betterphish.io/docs",
    "Upgrade to a paid tier for more scans and features"
  ]
}
Important: Save your API key immediately! It will only be shown once. If you lose it, you'll need to contact support.

Usage & Billing

GET /v1/usage/current

Get your current usage statistics and remaining quota.

Response

JSON 
{
  "api_key_name": "My App",
  "tier": "pro",
  "tier_name": "Pro",
  "scans_today": 4523,
  "scans_this_month": 89234,
  "daily_limit": 10000,
  "monthly_limit": 250000,
  "daily_remaining": 5477,
  "monthly_remaining": 160766,
  "rate_limit_per_min": 120,
  "ioc_feed_access": true,
  "enhanced_analysis": true
}
Full API Reference: Interactive API documentation with try-it-out functionality is available at spam.betterphish.io/docs