api reference
Categories and policies
The eight categories (business, personal, disposable, relay, education, government, invalid, unknown) and how the b2b, strict and lenient policies map them.
Every check returns a category (what the address is) and a recommendation (what to do about it under a policy). Categories are facts about the domain; policies are your business rules.
Categories
| Category | Meaning | Example |
|---|---|---|
business |
The company’s own custom domain that receives mail | jane@acme.io |
personal |
A shared-domain provider: one domain, many unrelated people | jane@gmail.com, jane@outlook.com, ISP domains |
disposable |
Throwaway inbox, often valid for minutes | temporary-mail services |
relay |
Privacy relay forwarding to a hidden inbox | …@privaterelay.appleid.com, …@duck.com, …@mozmail.com |
education |
Schools and universities | .edu, .ac.uk, .edu.au, known university domains |
government |
Public sector | .gov, .gov.uk, .gouv.fr, .gc.ca, .mil, europa.eu |
invalid |
Can’t receive mail: bad syntax, non-existent domain, no MX or a null MX | jane@acme, jane@nonexistent-domain-123.com |
unknown |
A custom domain with too little evidence to call (very new, parked, no SPF/DMARC, forwarding-only mail) | a 3-day-old domain with no website |
is_business is true for business, education and government.
The core rule
A business email is on the company’s own custom domain. A personal email is on a shared domain. We ask “is this domain shared or custom?”, not “is this a big company?”. A one-person consultancy on jane-consulting.com is business. A Fortune 500 employee using @gmail.com is personal.
Lists decide most cases. For everything else, DNS signals adjust confidence. Strong evidence of a shared or disposable domain (consumer-only mail servers, mail servers shared by disposable services) overrides the “custom domain” default.
Precedence
When lists disagree, this order wins: admin override → blocked → disposable → relay → shared → education/government → custom. A more specific entry beats a parent domain, so alumni.university.edu can be personal while university.edu is education.
Policies
Choose with policy=b2b|strict|lenient. The default is b2b.
| Input | b2b (default) |
strict |
lenient |
|---|---|---|---|
business |
allow | allow | allow |
education |
allow | allow | allow |
government |
allow | allow | allow |
role account (info@, sales@…) on an allowed domain |
review | block | allow |
unknown |
review | block | allow |
personal |
block | block | allow |
relay |
block | block | allow |
disposable |
block | block | block |
invalid |
block | block | block |
blocked (is_blocked: true) |
block | block | block |
Blocked isn’t a category of its own. A blocklist match sets is_blocked: true with reason blocked_domain or blocked_email, and forces block under every policy. category still describes the domain.
Which policy should I use?
b2b: sales-led or PLG B2B products that want company signups but don’t want to lose edge cases.reviewgives you a middle lane.strict: products that require a company tenant from day one (for example, an integration that needs Microsoft 365 admin consent), or free trials with real abuse costs.lenient: consumer-friendly or freemium products that only want to keep out throwaway and broken addresses.
What to do with review
review means “probably fine, but look again”. Common handling:
- Let the user in and flag the account in your admin.
- Require email verification before the trial starts.
- Shorten the trial or hold back expensive features until a human approves.
- Route to sales for a quick qualification.
Policy vs your own rules
Policies are deliberately simple. If you need something else, for example “accept relay but only on paid plans”, call with any policy and decide from category and the flags yourself. The reason codes give you the full picture.