A disposable email checker API usually returns more than a yes or no, but most signup flows throw away everything except the boolean. That is a mistake. When you wire the response into your form handler, branch on the reason field instead of the bare verdict, because a blocklist match deserves a hard reject while a catch-all or role-account signal often calls for a softer step like sending a confirmation email. This guide walks through what these APIs actually return, what each field means, and how to turn that payload into signup logic that blocks abuse without punishing legitimate users.
What a disposable email checker API actually returns
Most services in this space follow a similar response shape. You send an address or a domain, and you get back a JSON object with a boolean (often called disposable, block, or is_disposable), a reason or category string, sometimes a confidence score, and occasionally metadata like the matched domain, the list that produced the match, and a timestamp. The boolean is the headline. The reason field is the story.
Typical reason values you will see in the wild include things like disposable (a domain on a known throwaway list), catch_all (the mail server accepts every address regardless of whether the mailbox exists), role_account (addresses like admin@, info@, support@), invalid_syntax, no_mx_record, and ok. Some vendors fold these into the boolean, some keep them separate, and some return an array of reasons when multiple signals fire at once. If your integration only reads the boolean, you are collapsing six distinct situations into one bit.
The underlying data comes from many places. The disposable-email-domains project is a community blocklist plus an allowlist, licensed under CC0, so you can vendor it directly into your codebase or load it at boot. FakeFilter publishes an automated list of temp-mail providers daily and offers an online API at fakefilter.net. MailChecker supports over 55,000 throwable email domains and ships on npm and PyPI. burner-email-providers is a plain list of temporary providers, easy to diff against your own. amieiro/disposable-email-domains regenerates aggregated deny and allow lists every 15 minutes on GitHub. Each has a different update cadence, a different license posture, and a different definition of what counts as disposable. That is why a single boolean from a single vendor is not enough context to make a good product decision.
Mapping each reason to the right signup action
Once you have the reason field in hand, the signup flow design becomes straightforward. You are not asking “is this email bad?” You are asking “what is the least hostile action that still protects the product?” A domain on a disposable blocklist is a strong signal that someone wants to burn the account. That deserves a hard reject with a clear error message. A catch-all domain might be a corporate mail server, a university, or a privacy-conscious provider. That deserves a confirmation email, not a block. A role account like info@ is usually a shared inbox, not a person, and often you want to reject it for personal signups but allow it for business onboarding.
Hard reject, soft verify, and allow with monitoring
Group your reasons into three buckets and code the buckets, not the individual strings. This keeps your handler readable and makes it easy to add new reasons when your vendor ships them.
- Hard reject: disposable from a trusted blocklist, invalid_syntax, no_mx_record. Return an error explaining that disposable addresses are not accepted, and log the matched domain so you can spot patterns.
- Soft verify: catch_all, role_account, greylisted, or low-confidence disposable matches. Let the signup through but require email confirmation before the account can do anything meaningful.
- Allow with monitoring: ok, or a match on a domain that also appears on your allowlist (for instance, a domain the disposable-email-domains project explicitly allows because it is a shared hosting provider, not a burner service).
- Defer: API timeouts, rate limits, or 5xx responses. Never hard-reject on an API failure. Fall back to your local copy of the list and let the signup proceed if the address is not on it.
That last point matters more than it sounds. Checker APIs go down, rate limits get hit, and DNS lookups time out. If your signup flow treats an API failure as a disposable signal, you will block real users during every vendor incident. Keep a local snapshot of the blocklist on disk, refresh it on a schedule, and use the API for the reasons it is uniquely good at: catch-all detection, role-account classification, and freshly registered domains that have not yet propagated to community lists.
The DeBounce free disposable-check endpoint is worth mentioning because it does not require an API key, which makes it easy to prototype the branching logic before you commit to a paid plan. Kickbox and similar vendors return richer reason taxonomies that map cleanly onto the three buckets above. If you are building your own checker to check if a domain is disposable, pull from disposable-email-domains, FakeFilter, MailChecker, burner-email-providers, and amieiro/disposable-email-domains together, deduplicate, and treat the union as your deny list. Note that ivolo/disposable-email-domains is no longer maintained, so do not rely on it as your only source. AllMail publishes a guide on disposable email domain lists that is a reasonable starting point for evaluating which lists are still active.
Wiring the response into your handler without blocking real users
The handler itself should be boring. Parse the response, extract the reason, normalize it to your internal enum, and route through a small decision function that returns an action. Keep the decision function pure and unit-test it against a fixture set of responses covering every reason you have seen in production. When your vendor adds a new reason, the test suite fails, you decide which bucket it belongs in, and you ship. That is the whole maintenance story.
Two operational details are easy to get wrong. First, cache results per domain, not per address, because most disposable providers rotate the local part and keep the domain. A short TTL (an hour is fine) cuts your API calls by an order of magnitude on any real signup volume. Second, log the reason alongside the outcome, not just the outcome. When a user complains they were blocked, you want to know whether it was a blocklist match, a catch-all heuristic, or a transient failure. Without the reason in the log, you are debugging blind.
Handle blocklist removal requests with a documented process. Community lists like disposable-email-domains accept pull requests on GitHub, and amieiro/disposable-email-domains regenerates every 15 minutes, so a fix can propagate quickly. If a legitimate domain lands on a list by mistake (it happens, especially with shared hosting and small regional providers), you want an allowlist override on your side so you are not waiting on someone else’s merge queue. Keep that override list small and reviewed, because an allowlist is a hole in your blocklist and holes tend to grow.
Finally, be honest about the trade-off. A disposable email checker will never be perfect. Catch-all detection produces false positives on legitimate corporate mail servers. Role-account detection flags real humans who happen to use a shared inbox. Freshly registered domains that are not actually disposable will occasionally appear on automated lists. The reason field is your lever for tuning that trade-off per signal instead of globally. A hard reject on a blocklist match costs you almost nothing because the false-positive rate is low. A hard reject on a catch-all signal costs you real customers because the false-positive rate is high. Same API, same response, two very different actions.
Start by logging the full response for a week before you change any behavior. Group your signups by reason and look at what each bucket contains. You will almost certainly find that disposable matches are junk, catch_all matches are a mix of legitimate businesses and lazy throwaway users, and role_account matches split cleanly by whether the signup used a personal or business form. Then write the branching logic to match what the data actually shows. The boolean was never the point. The reason is.