REST API Reference

API Overview & Architecture

The IsThisSpam Developer API provides low-latency, real-time threat intelligence and AI classification for emails, SMS messages, web URLs, and submission forms. Easily detect phishing attempts, scam campaigns, credential harvesters, and junk messages within your applications before they harm your users.

Base Production URL

https://isthisspam.org

Global Cloudflare Edge Network

Average Latency

< 80ms - 150ms

Optimized for synchronous gate checks

Payload Format

application/json

UTF-8 encoded JSON bodies

Security & Credentials

Authentication

All requests to the IsThisSpam Developer API must include your secret API key in the X-API-Key HTTP request header.

HTTP Header Format

http

X-API-Key: ists_live_9f83a8b27c6d1e45903b123456789abc

ists_live_*

Live Production Key

Used for real production traffic. Calls made with live keys count towards your active monthly quota.

ists_test_*

Sandbox / Development Key

Used for local development, automated integration testing, and CI/CD pipelines.

Keep your API key private: Never commit API keys to client-side code, browsers, or public GitHub repositories. Always store your key in environment variables (e.g. ISTHISSPAM_API_KEY) on your backend.

Get Running in 3 Steps

Quick Start

Get Your API Key

Log into your Developer Dashboard and click "Generate API Key" to get 100 free evaluation requests.

Send a Classification

Make an HTTP POST request to /api/v1/classify with your suspicious text or email payload.

Act on the Verdict

Use the returned classification, confidence, and reasons to block, flag, or quarantine the threat.

Core Threat Analysis

Classify Content

POST/api/v1/classify

Analyzes raw text, email bodies, SMS content, or website copy against IsThisSpam's multi-layered detection models to determine if it is Legitimate, Spam, Phishing, or Scam.

Request Headers

Header	Type	Required	Description
X-API-Key	string	Required	Your developer API key (e.g. `ists_live_...`).
Content-Type	string	Required	Must be `application/json`.

Request Body Parameters

Field	Type	Status	Description
content	string	Required	The text message, email body, or subject string to evaluate. Max length: 64,000 characters.
type	string	Optional	Content context hint. Allowed values: `"email"`, `"text"` (SMS/chat), or `"url"`. Defaults to `"email"`.
metadata.sender	string	Optional	Sender email address or phone number. Used for domain reputation and spoofing detection.
metadata.subject	string	Optional	Email subject line. Enhances context for urgent scam patterns.
metadata.trusted	boolean	Optional	Set to `true` if sender has passed internal SPF/DKIM verification.

Example JSON Request

POST /api/v1/classify

json

{
  "content": "Subject: Urgent: Your account access has been restricted\n\nPlease verify your credentials immediately at https://security-login-alert.com",
  "type": "email",
  "metadata": {
    "sender": "support@security-login-alert.com",
    "subject": "Urgent: Account Verification Required",
    "trusted": false
  }
}

Example 200 OK Response

Response Payload

json

{
  "classification": "Phishing",
  "isSpam": true,
  "confidence": 0.96,
  "reasons": [
    "High urgency language demanding immediate credential verification",
    "Sender domain does not match legitimate organization email records",
    "Contains deceptive destination URL targeting authentication forms"
  ],
  "recommendations": [
    "Do not click any links or attachments",
    "Do not provide credentials, OTPs, or payment information",
    "Block the sender address and quarantine the message"
  ],
  "usage": {
    "used": 42,
    "limit": 1000,
    "remaining": 958
  }
}

Response Attributes

Attribute	Type	Description
classification	string	Primary verdict category: `Legitimate`, `Spam`, `Phishing`, or `Scam`.
isSpam	boolean	Boolean shorthand indicator: `true` if any threat (Spam, Phishing, Scam) was detected; `false` if Legitimate.
confidence	number	AI model confidence score between `0.00` and `1.00`.
reasons	string[]	List of human-readable rationale points detailing why the verdict was rendered.
recommendations	string[]	Actionable security steps recommended for the user or automated workflow.
usage	object	Contains `used`, `limit`, and `remaining` requests for your billing cycle.

Account & Quotas

Check Usage & Limits

GET/api/v1/usage

Programmatically query your current API usage, remaining monthly calls, reset date, and active per-minute rate limits.

cURL Request

GET /api/v1/usage

bash

curl -X GET https://isthisspam.org/api/v1/usage \
  -H "X-API-Key: ists_live_your_key_here"

Example Response

200 OK

json

{
  "tier": "starter",
  "usage": {
    "used": 42,
    "limit": 25000,
    "remaining": 24958,
    "resetAt": "2026-09-01T00:00:00.000Z"
  },
  "rateLimit": {
    "perMinute": 60
  }
}

SDKs & Integration Snippets

Multi-Language Code Examples

Copy production-ready boilerplate in your language of choice to integrate threat classification in minutes.

terminal

bash

curl -X POST https://isthisspam.org/api/v1/classify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ists_live_your_key_here" \
  -d '{
    "content": "Subject: Urgent: Your account access has been restricted\n\nPlease verify your credentials immediately at https://security-login-alert.com",
    "type": "email",
    "metadata": {
      "sender": "support@security-login-alert.com",
      "subject": "Urgent: Account Verification Required"
    }
  }'

Error Handling

Status & Error Codes

The API uses standard HTTP response codes to indicate request success or failure. All errors return a JSON object containing an error message.

HTTP Code	Error Title	Description & Resolution
200 OK	Success	The request was successfully processed.
400 Bad Request	Missing content	The JSON body is malformed or missing the required `content` field.
401 Unauthorized	Invalid / Missing Key	No `X-API-Key` header was provided, or the key was not recognized.
403 Forbidden	Key Disabled / Restricted	The API key has been disabled or revoked. Generate a new key in your dashboard.
429 Too Many Requests	Quota / Rate Exceeded	You have exceeded your monthly limit or per-minute rate limit. Upgrade your plan to increase limits.
500 Server Error	Internal Error	An unexpected error occurred during classification. Retry with exponential backoff.

Example 429 Quota Error Payload

json

{
  "error": "Monthly limit exceeded",
  "limit": 1000,
  "used": 1000,
  "resetAt": "2026-09-01T00:00:00.000Z"
}

Throughput & Scaling

Rate Limits & Plan Quotas

API rate limits apply on a per-key basis. If you require dedicated throughput or higher volume allowances, you can upgrade your tier in the developer dashboard.

Tier	Monthly Calls	Rate Limit	SLA / Support	Plan
Free Evaluation	100 total	10 / min	Community	Free
Starter	25,000 / mo	60 / min	Email Support	$19 / mo
Business / Pro	250,000 / mo	300 / min	Priority Support	$99 / mo
Enterprise	Custom / Unlimited	1,000+ / min	Dedicated Slack / 99.99% SLA	Contact Us

Engineering Guidelines

Best Practices for Production

1. Secure Key Storage

Store keys in server secrets or key management systems (AWS Secrets Manager, Doppler, Vault). Never expose API keys in frontend bundles.

2. Implement Exponential Backoff

When receiving HTTP 429 or 5xx responses, implement exponential backoff with jitter to prevent cascading failures.

3. Cache Static Results

Hash identical repeated message bodies (e.g. SHA-256) in your local Redis cache to conserve API quota on high-frequency broadcast blasts.

4. Supply Sender Metadata

Always pass the sender address and subject line in metadata to enable deep sender domain reputation analysis.

Ready to Integrate?

Start protecting your users in under 5 minutes

Generate your API key, test live queries in the interactive sandbox, and integrate robust AI scam detection into your production workflows today.

Get Free API Key View Pricing Plans Contact Support

IsThisSpam API Documentation

API Overview & Architecture

Authentication

Quick Start

Get Your API Key

Send a Classification

Act on the Verdict

Classify Content

Request Headers

Request Body Parameters

Example JSON Request

Example 200 OK Response

Response Attributes

Check Usage & Limits

cURL Request

Example Response

Multi-Language Code Examples

Status & Error Codes

Rate Limits & Plan Quotas

Best Practices for Production

Start protecting your users in under 5 minutes