API Documentation

Complete reference for the DisposableGuard API. Check single emails or batch up to 100 at once.

Base URL

https://api.disposableguard.com/api/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer dg_live_...

Get your API key from the dashboard.

Check a single email

GET /api/v1/check?email=user@domain.com

Query Parameters

Parameter	Type	Required	Description
email	string	Yes	Email address to check

Response (200)

{
  "email": "test@mailinator.com",
  "domain": "mailinator.com",
  "is_disposable": true,
  "blocked": true,
  "reason": "Domain is a known disposable / temporary email provider.",
  "duration_ms": 2,
  "source": "local"
}

Response Fields

Field	Type	Description
email	string	The email address that was checked
domain	string	Domain extracted from the email
is_disposable	boolean	Whether the email uses a disposable provider
blocked	boolean	Same as is_disposable (convenience field)
reason	string	Human-readable explanation of the verdict
duration_ms	integer	Processing time in milliseconds
source	string	"local" (matched database) or "unknown" (not found)

Batch check emails

Check up to 100 email addresses in a single request. More efficient than individual calls.

POST /api/v1/check/batch

Request Body

{
  "emails": [
    "user@gmail.com",
    "test@mailinator.com",
    "admin@guerrillamail.com",
    "invalid-email"
  ]
}

Response (200)

{
  "results": [
    { "email": "user@gmail.com", "is_disposable": false, "source": "unknown" },
    { "email": "test@mailinator.com", "is_disposable": true, "source": "local" },
    { "email": "admin@guerrillamail.com", "is_disposable": true, "source": "local" },
    { "email": "invalid-email", "is_disposable": false, "source": "unknown" }
  ],
  "summary": {
    "total": 4,
    "disposable": 2,
    "legitimate": 1,
    "invalid": 1
  },
  "rate_limit": {
    "monthly_remaining": 496,
    "burst_remaining": 3
  },
  "duration_ms": 3
}

Error Codes

Status	Error	Meaning
400	bad_request	Missing or malformed email
401	invalid_api_key	API key is wrong or revoked
429	rate_limit_exceeded	Burst limit hit
429	plan_limit	Monthly cap hit

Rate Limits

Plan	Monthly	Burst
Free	500 / month	5 req / sec
Basic	10,000 / month	10 req / sec
Pro	100,000 / month	25 req / sec
Ultra	1,000,000 / month	50 req / sec

Database

Our database contains 164,628 disposable email domains aggregated from 6 open-source sources:

disposable/disposable (72,305 domains)
ivolo/disposable-email-domains (121,569 domains)
willwhite/freemail (88,173 domains)
groundcat/disposable-email-domain-list (27,120 domains)
martenson/disposable-email-domains (5,447 domains)
unkn0w/disposable-email-domain-list (3,617 domains)

After deduplication and filtering out legitimate providers: 164,628 unique disposable domains.