Trust2API

Disposable Email API

Detect disposable/throwaway email domains to reduce fraud and improve list quality.

Project: Disposable Fake Mail Shield API

A production-ready HTTP API for detecting disposable/temporary email domains. It helps you keep fake sign-ups and low-quality leads out of your system by validating whether an email domain is disposable.

  • Base RapidAPI URL: https://disposable-fake-mail-shield.p.rapidapi.com
  • Required headers (RapidAPI):
    • X-RapidAPI-Key: <your-rapidapi-key>
    • X-RapidAPI-Host: disposable-fake-mail-shield.p.rapidapi.com

What this service does

  • Validates if a domain belongs to a disposable/temporary email provider
  • Works with single or bulk domain inputs
  • Returns machine-friendly JSON responses, response timing, and version headers
  • Designed to be used at signup, newsletter subscription, and lead capture flows

How it works (under the hood)

  • Maintains a curated, versioned list of known disposable email domains (and subdomains)
  • Normalizes and validates input domains (punycode, lowercase, public suffix handling)
  • Checks candidate domains against the disposable list with fast lookups
  • Applies an allowlist so you can explicitly permit certain domains even if they appear on third-party lists
  • Returns a boolean result per domain with minimal latency

If available in your plan, the service may add helpful response headers for observability:

  • X-Elapsed – processing time in microseconds
  • X-Region – region of the responding node
  • X-Version – service version
  • X-RapidAPI-Billing – usage accounting for bulk requests (if applicable)

Quick start

  1. Subscribe on RapidAPI (pick a plan that suits your volume)
  2. Get your X-RapidAPI-Key
  3. Call one of the endpoints below with your key and host

Endpoints

Health

  • GET /health
  • Purpose: lightweight liveness/probe check
  • Response: 200 OK with a short JSON body

Single domain validation

  • GET /validate?domain={domain}
  • Query params:
    • domain (required): the domain part of an email, e.g., gmail.com
  • Response 200 OK (example):
{
  "status": true,
  "message": "gmail.com is not a disposable domain",
  "data": {
    "domain": "gmail.com",
    "disposable": false
  }
}

Bulk validation

  • POST /validate
  • Body:
{
  "domains": [
    "123.com",
    "tempmail.example"
  ]
}
  • Response 200 OK (example):
{
  "status": true,
  "message": "",
  "data": [
    { "domain": "123.com", "disposable": false },
    { "domain": "tempmail.example", "disposable": true }
  ],
  "count": 2
}

Developer docs (if enabled)

  • GET /docs – interactive API UI
  • GET /docs/openapi.yaml – OpenAPI spec

Authentication

Use RapidAPI headers on every request:

  • X-RapidAPI-Key: <your-rapidapi-key>
  • X-RapidAPI-Host: disposable-fake-mail-shield.p.rapidapi.com

If you are calling a self-hosted version (outside RapidAPI), you may instead need an internal header like X-Api-Key: <your-secret-key>.

cURL examples

Single domain:

curl --get --include "https://disposable-fake-mail-shield.p.rapidapi.com/validate" \
  --data-urlencode "domain=gmail.com" \
  -H "X-RapidAPI-Key: <your-rapidapi-key>" \
  -H "X-RapidAPI-Host: disposable-fake-mail-shield.p.rapidapi.com"

Bulk domains:

curl --request POST \
  --url "https://disposable-fake-mail-shield.p.rapidapi.com/validate" \
  -H "content-type: application/json" \
  -H "X-RapidAPI-Key: <your-rapidapi-key>" \
  -H "X-RapidAPI-Host: disposable-fake-mail-shield.p.rapidapi.com" \
  --data '{"domains":["123.com","tempmail.example"]}'

JavaScript (fetch) example

async function checkDomain(domain) {
  const url = new URL("https://disposable-fake-mail-shield.p.rapidapi.com/validate");
  url.searchParams.set("domain", domain);

  const res = await fetch(url, {
    headers: {
      "X-RapidAPI-Key": process.env.RAPIDAPI_KEY,
      "X-RapidAPI-Host": "disposable-fake-mail-shield.p.rapidapi.com"
    }
  });

  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  return res.json();
}

Python (requests) example

import os
import requests

base = "https://disposable-fake-mail-shield.p.rapidapi.com"
headers = {
    "X-RapidAPI-Key": os.environ.get("RAPIDAPI_KEY"),
    "X-RapidAPI-Host": "disposable-fake-mail-shield.p.rapidapi.com",
}

# Single
r = requests.get(f"{base}/validate", params={"domain": "gmail.com"}, headers=headers)
r.raise_for_status()
print(r.json())

# Bulk
payload = {"domains": ["123.com", "tempmail.example"]}
r = requests.post(f"{base}/validate", json=payload, headers=headers)
r.raise_for_status()
print(r.json())

Error handling

  • 400 Bad Request – malformed input (e.g., missing domain or invalid JSON)
  • 401 Unauthorized – missing/invalid RapidAPI key
  • 403 Forbidden – plan does not allow the attempted operation
  • 404 Not Found – wrong path
  • 429 Too Many Requests – rate limit exceeded
  • 5xx – server-side error

Example error body:

{
  "message": "validation error",
  "status": false
}

Client best practices:

  • Validate domains client-side before calling the API
  • Implement retries with jitter for 5xx and backoff for 429
  • Cache negative results briefly if your UX can tolerate it

Integration tips

  • Call the API right after a user enters their email and before creating the account
  • If disposable: true, show a friendly message asking for a permanent email
  • Log the X-Elapsed and X-Version headers to help support/observability
  • For bulk imports, prefer POST /validate with batches of 100–1000 domains depending on your plan limits

Security and privacy

  • Do not send full email addresses; only send the domain part
  • Use HTTPS only
  • Rotate your RapidAPI key periodically and store it in a secret manager
  • Follow principle of least privilege for CI/CD where keys are present

Rate limits and pricing

  • Enforced by your RapidAPI plan. Exceeding limits returns 429 with headers indicating quota usage when available.
  • Consider exponential backoff and request spreading for high-throughput systems.

Changelog and versioning

  • The service publishes versions via X-Version
  • Disposable domain datasets are periodically updated; bulk changes may occur when upstream lists update

FAQ

  • Q: Can I validate full emails?
    • A: The API validates domains. Extract the domain client-side from the email address before calling.
  • Q: How accurate is the list?
    • A: It tracks known disposable providers and is updated regularly, but no dataset is perfect. Use allowlists/overrides for your business needs.
  • Q: What about subdomains?
    • A: Subdomains are normalized and checked relative to public suffix rules to avoid false positives.