# isitreal > Disposable-email detection that reads an address's live mail infrastructure instead of maintaining a blocklist. One API call, before the account exists. Base URL: https://www.isitreal.email Auth: Authorization: Bearer ## Quickstart One POST per address, answered before the account is written. Create a key in the dashboard, put it in the environment, and call the endpoint. Gate the signup on allowed. ```bash curl -X POST https://www.isitreal.email/api/v1/check \ -H 'Authorization: Bearer $ISITREAL_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"email":"user@mailinator.com"}' ``` ## Authentication Send your key as a bearer token. An API key is the only way to call the API — there is no anonymous access, and a dashboard session is deliberately not accepted here, so an extracted browser token cannot be used as a free key. Keys are shown once at creation and stored only as a SHA-256 hash. A lost key cannot be recovered; revoke it and make another. Keys require an active plan. A key belonging to an account with no subscription returns 402. To try the product before subscribing, use the playground in the dashboard. ```bash Authorization: Bearer isr_your_key_here ``` ## POST /api/v1/check Takes one address. Returns a verdict. Every response carries X-Quota-Limit and X-Quota-Used headers when the caller is authenticated. ```json { "email": "user@mailinator.com" } ``` ```json { "email": "user@mailinator.com", "domain": "mailinator.com", "canonical_email": "user@mailinator.com", "is_alias": false, "decision": "BLOCK", "allowed": false, "reason": "domain is on the disposable blocklist", "decided_by": "L2_blocklist", "score": 1, "signals": { "blocklist": true }, "latency_ms": 0, "cached": true } ``` ## POST /api/v1/check/batch Takes up to 500 addresses and fans them out internally with bounded concurrency. Counts one check per address against your quota, not one per request. Rejects the whole batch with 413 if it is over the limit, and with 429 if it would take you past your monthly quota. ```json { "emails": ["a@gmail.com", "b@mailinator.com"] } ``` ## Decisions Gate on allowed for the simple case. Branch on decision when you want the third option — REVIEW is what keeps hard-block precision at 100%, because a borderline score does not have to become a rejection. ALLOW — sign them up. REVIEW — sign them up, but require verification or withhold free credits. BLOCK — refuse. ## Which layer decided decided_by names the cheapest layer that reached a conclusion. Most traffic never reaches the model. L0_syntax — malformed address. L2_blocklist — the domain is on the disposable blocklist. L1_unreachable — the domain cannot receive mail (no MX, NXDOMAIN, or an RFC 7505 null MX). L3_mx_operator — mail is handled by a known throwaway backend, or by a mail server shared with other website-less domains (how temp-mail services rotate domains). L4_model — a genuinely unknown domain, sent to the model. L4_degraded — the model was unreachable; the verdict came from the deterministic layers alone. ## Alias abuse Plus-addressing and Gmail dot tricks produce real, deliverable mailboxes, so they are allowed. They are also the same inbox. Enforce uniqueness on canonical_email rather than on the raw address and plus-address farming dies without a model call. a.d.a.r.s.h+signup42@gmail.com and adarsh@gmail.com share one canonical_email. is_alias tells you it was rewritten. ## Failure and fail-open The classifier fails open by design. If the model layer cannot be reached, the response still arrives with decided_by set to L4_degraded and degraded: true, decided by the deterministic layers. Your signup form is never held up by our outage. Your own client should fail open too: use a short timeout, and on timeout or a non-2xx, let the signup through. ## Status codes 200 — a verdict, even a degraded one. 400 — the body was not {"email": "..."}. 401 — missing, malformed, revoked, or unknown key, or a dashboard session used against the API. 402 — the key is valid but the account has no active plan. 413 — more than 500 addresses in a batch. 429 — either the anonymous demo rate limit (Retry-After header) or your monthly quota. The quota body carries used, quota and an upgrade path. Treat 429 as fail-open and log it. A spent quota should not cost you a real customer. ## Caching and cost A verdict is cached per domain for 24 hours. Concurrent checks of the same cold domain collapse into a single lookup, so fifty simultaneous signups from one new domain cost one model call, not fifty. cached: true tells you the answer came from that cache. Quota counts addresses you send, not model calls we make. ## GET /api/health Liveness with no dependencies. Returns {"status":"ok","service":"isitreal"}. Use /api/ready when you want the dependency check instead.