DISIFY API Documentation

Email validation API with disposable detection, DNS/MX validation, SPF/DKIM/DMARC checks, domain age, deliverability scoring, and more. Free tier available — no API key required.

Quick Start

No signup or API key needed. Make your first request in seconds:

curl https://disify.com/api/email/[email protected]

import requests

response = requests.get("https://disify.com/api/email/[email protected]")
data = response.json()

if data.get("disposable"):
    print("Disposable email detected!")
else:
    print("Email looks legitimate.")

const response = await fetch("https://disify.com/api/email/[email protected]");
const data = await response.json();

if (data.disposable) {
    console.log("Disposable email detected!");
} else {
    console.log("Email looks legitimate.");
}

$response = file_get_contents("https://disify.com/api/email/[email protected]");
$data = json_decode($response, true);

if ($data['disposable']) {
    echo "Disposable email detected!";
} else {
    echo "Email looks legitimate.";
}

Example response:

{
    "format": true,
    "domain": "gmail.com",
    "disposable": false,
    "dns": true,
    "confidence": 0,
    "whitelist": true,
    "domain_info": {
        "tld": "com",
        "is_subdomain": false,
        "parent_domain": null
    },
    "mx_info": [
        "gmail-smtp-in.l.google.com",
        "alt1.gmail-smtp-in.l.google.com"
    ],
    "role": false,
    "free": true
}

Base URL

All API requests use the following base URL:

The API returns application/json responses for all endpoints. CORS is enabled, so you can make requests directly from the browser.

Rate Limiting

To keep the service available for everyone, requests are rate-limited per IP (anonymous) or per API key (authenticated).

Rate limit headers are included in every response:

• X-RateLimit-Limit — your per-minute limit
• X-RateLimit-Remaining — requests remaining in the current window

• Exceeding the limit returns 429 Too Many Requests.
• Sustained abusive traffic may result in an automatic IP ban.
• Consider caching results on your side for domains you check frequently.

Authentication

The API works without authentication for core features. For higher monthly limits, API keys, and premium features, create a free account and use an API key.

API Key

Pass your API key in the X-Api-Key header or Authorization: Bearer header:

# X-Api-Key header
curl -H "X-Api-Key: YOUR_API_KEY" https://disify.com/api/email/[email protected]

# Authorization Bearer header
curl -H "Authorization: Bearer YOUR_API_KEY" https://disify.com/api/email/[email protected]

Usage tiers

See pricing for full details and credit packs.

Premium Features

Request premium features by adding them to the URL path or as a features parameter. If your tier doesn't include a requested feature, the response will contain a requires_upgrade array listing the denied features.

# Request SPF and DKIM checks via URL path
curl -H "X-Api-Key: YOUR_KEY" https://disify.com/api/email/[email protected]/spf/dkim

# Request multiple features via query parameter
curl -H "X-Api-Key: YOUR_KEY" "https://disify.com/api/email/[email protected]?features=spf,dkim,dmarc"

Available premium features

spam_trap detection is automatically included for Pro tier users — no need to request it.

Pro tier response example

{
    "format": true,
    "domain": "example.com",
    "disposable": false,
    "dns": true,
    "confidence": 0,
    "domain_info": {
        "tld": "com",
        "is_subdomain": false,
        "parent_domain": null
    },
    "mx_info": ["mx1.example.com", "mx2.example.com"],
    "spam_trap": {
        "is_trap": false,
        "type": null,
        "reason": null
    },
    "email_auth": {
        "spf": "pass",
        "spf_record": "v=spf1 include:_spf.google.com ~all",
        "dmarc": {
            "policy": "reject",
            "record": "v=DMARC1; p=reject; rua=mailto:[email protected]",
            "subdomain_policy": "quarantine",
            "pct": 100,
            "rua": "mailto:[email protected]"
        },
        "dkim_configured": true,
        "dkim_selectors_found": ["google", "selector1"]
    },
    "domain_age": {
        "registered": "2015-06-01",
        "age_days": 3848,
        "fresh": false
    },
    "inbox_provider": "Google Workspace",
    "deliverability_score": 100,
    "role": false,
    "free": false
}

Single Email Check

Validates a single email address. Checks format, DNS/MX records, and whether the domain is a known disposable email provider.

GET Request

curl https://disify.com/api/email/[email protected]

POST Request

Send the email address as a form parameter:

curl -X POST https://disify.com/api/email \
     -d "[email protected]"

import requests

response = requests.post("https://disify.com/api/email", data={
    "email": "[email protected]"
})
print(response.json())

const response = await fetch("https://disify.com/api/email", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: "[email protected]"
});
const data = await response.json();

$ch = curl_init("https://disify.com/api/email");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, "[email protected]");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

POST Parameters

Response for a disposable email:

{
    "format": true,
    "domain": "tempmail.com",
    "disposable": true,
    "dns": true,
    "confidence": 100,
    "domain_info": {
        "tld": "com",
        "is_subdomain": false,
        "parent_domain": null
    },
    "mx_info": ["mx1.tempmail.com"],
    "signals": [
        "keyword_match",
        "mx_blacklist_exact"
    ],
    "role": false,
    "free": false
}

Response for a legitimate email:

{
    "format": true,
    "domain": "gmail.com",
    "disposable": false,
    "dns": true,
    "confidence": 0,
    "whitelist": true,
    "domain_info": {
        "tld": "com",
        "is_subdomain": false,
        "parent_domain": null
    },
    "mx_info": [
        "gmail-smtp-in.l.google.com",
        "alt1.gmail-smtp-in.l.google.com"
    ],
    "role": false,
    "free": true
}

Domain Check

Check a domain name directly, without needing a full email address. Uses the same detection engine.

curl https://disify.com/api/domain/guerrillamail.com

POST Parameters

Bulk Validation

Validate multiple email addresses or domains in a single request. Per-request limits depend on your tier (10,000 anonymous → 100,000 on Pro — see Authentication).

GET Request

Pass comma-separated emails directly in the URL with the /mass suffix:

curl "https://disify.com/api/email/[email protected],[email protected]/mass"

POST Request

Send the bulk parameter alongside comma-separated emails:

curl -X POST https://disify.com/api/email \
     -d "bulk=true" \
     -d "[email protected],[email protected],[email protected]"

import requests

response = requests.post("https://disify.com/api/email", data={
    "bulk": True,
    "email": "[email protected],[email protected],[email protected]"
})
print(response.json())

$ch = curl_init("https://disify.com/api/email");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    "bulk"  => true,
    "email" => "[email protected],[email protected],[email protected]"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

POST Parameters

Bulk Response

{
    "total": 3,
    "invalid_format": 0,
    "invalid_dns": 0,
    "disposable": 1,
    "unique": 3,
    "valid": 2,
    "session": "d117271ce938bf91bc718f6cfb7954de"
}

Bulk Response Fields

View Bulk Results

After a bulk validation, use the session hash to retrieve the list of valid email addresses. The response body is plain text — one valid address per line by default.

curl https://disify.com/api/view/d117271ce938bf91bc718f6cfb7954de

Optional Suffixes

You can combine suffixes in any order:

# Comma-separated + download
curl https://disify.com/api/view/d117271ce938bf91bc718f6cfb7954de/separator/download

Async bulk jobs (> 500 emails)

Bulk requests under 500 unique addresses are processed synchronously and return the stats response immediately. Larger batches are queued and return a pending response:

{
    "session": "d117271ce938bf91bc718f6cfb7954de",
    "status": "pending",
    "email_count": 8000,
    "estimated_seconds": 32
}

Poll GET /api/view/{session} for progress. While still running, the same endpoint returns JSON with a status of pending, processing, or failed:

{
    "session": "d117271ce938bf91bc718f6cfb7954de",
    "status": "processing",
    "email_count": 8000,
    "processed_count": 3200
}

Once status: "completed", the endpoint returns the plain-text valid list (with the suffix options above). If you configured a webhook on your account, you'll also receive a bulk.completed event with the final stats.

Response Fields

Every single email/domain check returns a JSON object with the following fields:

Detection Signals

When disposable is true, the signals array explains which detection layers matched:

Confidence Scoring

The confidence field (0–100) indicates how certain DISIFY is that the domain is disposable:

Plus-alias Temp-Mail Detection

A growing class of temp-mail services hands out plus-aliases on real Gmail, Outlook, Hotmail, Live, MSN, and iCloud mailboxes instead of running their own domain. Every alias routes to the same physical inbox, which the service scrapes. Because the base mailbox is a legitimate provider, checking the domain alone is not enough.

Disify keeps a list of known base accounts and canonicalizes every email before comparing:

• Lowercase the local-part and domain.
• Strip everything from + to @ (the plus-alias tag).
• Map googlemail.com → gmail.com.
• For gmail.com only: remove dots from the local-part (Google's documented policy).
• Microsoft (outlook/hotmail/live/msn) and Apple (icloud/me/mac) treat dots as literal — dots are not stripped.

If the canonical form matches a known base account, the response is:

{
    "format": true,
    "alias": true,
    "domain": "gmail.com",
    "disposable": true,
    "dns": true,
    "whitelist": true,
    "confidence": 100,
    "signals": ["alias_base_exact"]
}

Error Handling

If the request is malformed or missing required parameters, the API returns an error object:

{
    "error": "Invalid request"
}

Common error scenarios:

• No email/domain parameter — the email or domain field is missing or empty.
• Invalid format — "format": false is returned instead of an error. The response still includes other fields.
• Rate limited — Too many requests. Slow down and retry after a brief pause.

Blacklists

DISIFY maintains two public blacklists that power the detection engine:

The MX blacklist catches disposable services that rotate domains but continue using the same mail servers — providing an additional layer of detection beyond simple domain matching.

Community Submissions

Help improve DISIFY's blacklist by submitting domains you've identified as disposable, or requesting removal of domains that were incorrectly flagged:

• Submit or request removal directly on the website.
• All submissions are manually reviewed before being applied.
• Frequently submitted domains are prioritized for review.

Tips & Best Practices

1. Cache by domain, not by email — Domain-level disposable status rarely changes, so caching the result keyed on the domain is safe for 24h+. Don't cache per-email on gmail.com / outlook.com / icloud.com and friends — we run per-email plus-alias checks on those (see below).
2. Always check every email, including popular providers — We detect temp-mail services that ride on real Gmail/Outlook/iCloud mailboxes using plus-alias (and Gmail's dot-trick). Skipping Gmail/Outlook/Yahoo client-side will miss these. Use the whitelist: true response flag if you want to treat trusted-domain results more leniently, but still run the call.
3. Use the confidence score — For critical flows (e.g., account registration), you may want to only block confidence ≥ 90. For less critical checks, blocking any disposable: true is fine.
4. Check dns too — A domain that isn't disposable but has no MX records ("dns": false) can't receive email either.
5. Handle missing fields gracefully — Optional fields like alias, whitelist, and signals are omitted when not applicable. Always check for existence before reading.
6. Combine with your own checks — DISIFY handles disposable detection, DNS validation, and advanced email authentication checks (Pro). You should still validate that the email format is correct on your end.

Questions or issues? Open an issue on GitHub or submit feedback.