API Reference

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

Base URL

https://isdisposable.com/api

Authentication

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

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

Free tier

Create a free account to get an API key with 100 checks/month. No credit card required.

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."
}