API Reference

The isDisposable API provides real-time email validation with DNS checks, risk scoring, and domain age detection.

Base URL

https://api.isdisposable.com

Authentication

Pass your API key in the x-api-key header.

Terminalbash
curl -X POST https://api.isdisposable.com/v1/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: isd_live_your_key_here" \
  -d '{"email": "test@mailinator.com"}'

Public access

The API works without an API key (10 requests/day per IP) for testing. Add an API key to unlock higher limits and full features like DNS checks.

SDK client

Instead of raw HTTP calls, you can use the built-in API client from the same npm package. It handles authentication, caching, timeouts, and offline fallback automatically.

sdk-client.tstypescript
import { createIsDisposable } from '@isdisposable/js';

const client = createIsDisposable({
  apiKey: 'isd_live_your_key_here',
  // timeout: 5000,     // request timeout in ms (default: 5000)
  // cache: true,       // enable result caching (default: true)
  // cacheTTL: 3600,    // cache duration in seconds (default: 1 hour)
});

// Single check
const result = await client.check('test@mailinator.com');
// → { disposable: true, score: 95, reason: 'blocklist_match', ... }

// Bulk check (up to 100 emails)
const results = await client.checkBulk([
  'user@mailinator.com',
  'real@gmail.com',
]);

// Clear cached results
client.clearCache();

Automatic fallback

If the API is unreachable (network error, timeout, server down), the client automatically falls back to the offline blocklist. Your app will never break.
POST/v1/check

Check a single email address.

Request body

emailrequired
stringThe email address to check.
Requestjson
{
  "email": "test@mailinator.com"
}

Response

200 OKjson
{
  "disposable": true,
  "email": "test@mailinator.com",
  "domain": "mailinator.com",
  "score": 95,
  "reason": "blocklist_match",
  "mx_valid": true,
  "domain_age_days": 4380,
  "cached": false
}

Response fields

disposable
booleanWhether the email is from a disposable provider.
email
stringThe email that was checked (lowercase).
domain
stringThe domain part of the email.
score
numberRisk score from 0 (safe) to 100 (definitely disposable).
reason
stringWhy the email was flagged. One of: blocklist_match, mx_invalid, suspicious_mx, domain_new, custom_block, custom_allow, clean.
mx_valid
booleanWhether the domain has valid MX records. Only present with API key.
domain_age_days
numberDays since the domain was registered. Only present with API key.
cached
booleanWhether this result was served from cache.

Score calculation

The risk score is a composite of multiple signals:

SignalScore impact
Domain in blocklist (160k+ domains)+95
No valid MX records+40
Domain registered < 7 days ago+30
MX points to known disposable infra+20
Domain registered < 30 days ago+15
Valid MX + old domain + not in blocklist= 5

Score is capped at 100. An email is considered disposable when score ≥ 50.

POST/v1/check/bulk

Check up to 100 emails in a single request. Requires an API key.

Request body

emailsrequired
string[]Array of email addresses to check (max 100).
Requestjson
{
  "emails": [
    "user@mailinator.com",
    "real@gmail.com",
    "temp@guerrillamail.com"
  ]
}
200 OKjson
{
  "results": [
    {
      "disposable": true,
      "email": "user@mailinator.com",
      "domain": "mailinator.com",
      "score": 95,
      "reason": "blocklist_match",
      "mx_valid": true,
      "cached": false
    },
    {
      "disposable": false,
      "email": "real@gmail.com",
      "domain": "gmail.com",
      "score": 5,
      "reason": "clean",
      "mx_valid": true,
      "cached": false
    },
    ...
  ]
}
GET/v1/health

Check API status. No authentication required.

200 OKjson
{
  "status": "ok",
  "version": "1.0.0"
}

Error responses

StatusMeaning
400Invalid or missing email
401Invalid API key
429Rate limit or monthly limit exceeded
500Internal server error
429 Too Many Requestsjson
{
  "error": "Rate limit exceeded. Slow down."
}