← Back to Quick Start

Detect Disposable Emails to Protect Your Signups

Block throwaway email addresses at registration time with a multi-layer detection pipeline.

What you'll learn

  • How to check a single email against the disposable domain database
  • How to interpret the multi-layer detection result (static list, DNS, pattern matching)
  • How to batch-check up to 100 emails in a single request
  • How to look up a domain directly without providing a full email

Prerequisites

Step 1: Your first call

Check whether an email address belongs to a known disposable email provider:

curl -s -X POST /api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"email": "throwaway@guerrillamail.com"}' | python3 -m json.tool

Expected response:

{
  "email": "throwaway@guerrillamail.com",
  "domain": "guerrillamail.com",
  "disposable": true,
  "confidence": "HIGH",
  "detectionLayers": {
    "staticList": true,
    "dnsCheck": true,
    "patternMatch": false
  },
  "reason": "Domain found in static disposable domain list",
  "processingTimeMs": 8
}

Step 2: Understanding the response

disposable Boolean verdict: true if the domain is a known disposable provider.
confidence HIGH, MEDIUM, or LOW — based on how many detection layers matched.
detectionLayers Shows which layers flagged the domain: staticList (curated database), dnsCheck (DNS MX analysis), patternMatch (heuristic patterns).
reason Human-readable explanation of the detection result.

Step 3: Common use cases

Checking a legitimate email

curl -s -X POST /api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"email": "user@gmail.com"}'
{
  "email": "user@gmail.com",
  "domain": "gmail.com",
  "disposable": false,
  "confidence": "HIGH",
  "detectionLayers": {
    "staticList": false,
    "dnsCheck": false,
    "patternMatch": false
  },
  "reason": "Domain is not a known disposable provider",
  "processingTimeMs": 3
}

Domain-only lookup

Check a domain without providing a full email address:

curl -s /api/v1/domains/mailinator.com \
  -H "X-API-Key: YOUR_API_KEY"
{
  "domain": "mailinator.com",
  "disposable": true,
  "source": "STATIC_LIST",
  "addedDate": "2024-01-15"
}

Batch check (up to 100 emails)

curl -s -X POST /api/v1/check/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "emails": [
      "user@gmail.com",
      "test@guerrillamail.com",
      "admin@company.org"
    ]
  }'
{
  "totalChecked": 3,
  "disposableCount": 1,
  "results": [
    {"email": "user@gmail.com", "disposable": false, "confidence": "HIGH"},
    {"email": "test@guerrillamail.com", "disposable": true, "confidence": "HIGH"},
    {"email": "admin@company.org", "disposable": false, "confidence": "HIGH"}
  ],
  "processingTimeMs": 15
}

Step 4: Handling errors

Invalid email format

curl -s -X POST /api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"email": "not-an-email"}'
{
  "error": "VALIDATION_ERROR",
  "message": "email: must be a well-formed email address",
  "status": 400
}

Rate limiting (HTTP 429)

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Retry after 1 second."
}

Step 5: Integration tips

Python registration guard

import requests

API_BASE = ""
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}

def is_disposable(email):
    resp = requests.post(
        f"{API_BASE}/api/v1/check",
        json={"email": email},
        headers=HEADERS, verify=False
    )
    resp.raise_for_status()
    return resp.json()["disposable"]

# In your registration handler:
email = "newuser@tempmail.org"
if is_disposable(email):
    print("Registration blocked: disposable email detected")
else:
    print("Email accepted, proceeding with registration")

Batch validation for CSV imports

import requests, csv

def check_emails_batch(email_list):
    resp = requests.post(
        f"{API_BASE}/api/v1/check/batch",
        json={"emails": email_list},
        headers=HEADERS, verify=False
    )
    resp.raise_for_status()
    return resp.json()["results"]

# Read emails from CSV and check in batches of 100
with open("leads.csv") as f:
    emails = [row["email"] for row in csv.DictReader(f)]

for i in range(0, len(emails), 100):
    batch = emails[i:i+100]
    results = check_emails_batch(batch)
    for r in results:
        if r["disposable"]:
            print(f"DISPOSABLE: {r['email']}")

Next steps