Reason codes

reasons is an array of machine-readable codes explaining a verdict, strongest first. Use them for logging, analytics, support answers and your own rules.

"reasons": ["mx_google_workspace", "dmarc_reject", "txt_saas_tokens:3"]

• Some codes carry a count suffix after a colon: txt_saas_tokens:3 means three SaaS verification tokens were found. Split on : before matching.
• New codes may be added within /v1. Treat unknown codes as informational, never as errors.
• The Effect column is a guide to direction, not a weight. Weights are tuned on our evaluation set and change between engine versions.

Effects: → category sets the category outright · + raises business confidence · − lowers it · flag sets a flag without changing the category · info is context only.

Input and syntax

Code	Meaning	Effect
invalid_syntax	The address or domain isn’t syntactically valid (bad characters, missing @, empty labels, length limits)	→ invalid
invalid_domain	The domain doesn’t exist in DNS, or isn’t a registrable domain (e.g. only a public suffix)	→ invalid
no_mx	No MX records and no address record to fall back to, so the domain can’t receive mail	→ invalid
null_mx	The domain publishes a null MX (MX 0 ., RFC 7505): it explicitly accepts no mail	→ invalid
role_account	The local part is a role, not a person: info, sales, support, admin, noreply…	flag; review under b2b, block under strict
shared_inbox_name	The local part looks like a shared inbox, one mailbox several people answer from (support, billing, sales-eu…); see shared_inbox	flag (low confidence)
group_name	The local part looks like a group that forwards to many members (team, all, berlin-team…); see group	flag (low confidence)
google_group	The address is at googlegroups.com, so it is a Google Group	flag
subaddress	The address has a +tag; normalized_email has it removed	flag
typo_suspected	The domain is within a small edit distance of a popular provider (e.g. gmial.com); see did_you_mean	flag, −
lookalike_domain	The domain imitates a popular provider with confusable characters or punycode	flag, −

List matches

Code	Meaning	Effect
custom_domain	Not on any shared, disposable or relay list: the organization’s own domain	+ (baseline for business)
shared_provider	On our shared-domain provider list (gmail.com, outlook.com, yahoo.com, regional webmail, ISP domains…)	→ personal
disposable_provider	On our disposable list (throwaway inbox services)	→ disposable
relay_service	A privacy relay (Apple Hide My Email, Firefox Relay, DuckDuckGo, SimpleLogin, addy.io)	→ relay
education_domain	An education suffix (.edu, .ac.*, .edu.*) or a known university domain	→ education
government_domain	A government suffix (.gov, .gov.*, .gouv.fr, .gc.ca, .mil) or a known public-sector domain	→ government
business_allowlist	On our business allowlist: a verified company domain whose DNS might otherwise look unusual	→ business
blocked_domain	On our blocklist, built from spam and abuse reports	is_blocked; block under every policy
blocked_email	The exact address is on our blocklist (stored as a hash). Returned to secret keys only.	is_blocked; block under every policy
admin_override	A person on our team reviewed this domain and set its category	→ the reviewed category

MX fingerprints

Who receives mail for the domain, from its MX hosts.

Code	Meaning	Effect
mx_google_workspace	MX is Google Workspace (aspmx.l.google.com, smtp.google.com)	+ strong; Workspace evidence
mx_google_consumer	MX is consumer Gmail (gmail-smtp-in.l.google.com)	→ personal
mx_microsoft_365	MX is Exchange Online (*.mail.protection.outlook.com)	+ strong; Microsoft 365 evidence
mx_outlook_consumer	MX is consumer Outlook.com (*.olc.protection.outlook.com)	→ personal
mx_yahoo_consumer	MX is consumer Yahoo Mail (*.yahoodns.net)	→ personal
mx_enterprise_gateway	MX is a corporate email-security gateway (Proofpoint, Mimecast, Cisco, Barracuda, Trend Micro, Sophos, Hornetsecurity, Broadcom/Symantec)	+ strong
mx_hosting_provider	MX is a web-hosting company’s mail service	+ moderate
mx_consumer_host	A custom domain hosted on a consumer-oriented mail service (e.g. iCloud+ custom domains, Fastmail). Still business, with lower confidence.	+ weak
mx_forwarding_service	MX is a mail-forwarding service: the domain has no mailboxes of its own	−
mx_shared_disposable	The MX host also serves three or more known disposable domains	→ disposable
mx_shared_provider	The MX host also serves several known shared (free-mail) domains: an alias or regional domain of a webmail provider	→ personal
disposable_name	The domain name itself advertises a throwaway inbox (temp, trash, spam, fake, burner…) and there is no evidence of a real organization	→ disposable
mail_service_name	The domain name suggests a mailbox service (…mail, inbox…) and there is no evidence of a real organization (Workspace/M365/gateway MX, SaaS tokens, an Entra tenant)	→ unknown (review)
mx_other_suite	MX is another business suite (Zoho, Proton, Yandex 360, Microsoft 365 resellers…); see workspace.other_suite	+

Authentication records

Code	Meaning	Effect
spf_present	The domain publishes an SPF record	+
spf_business_saas	SPF includes business senders: HubSpot, Salesforce, Zendesk, Intercom, SendGrid, Mailgun, Mailchimp, Amazon SES…	+
dmarc_reject	DMARC policy p=reject	+
dmarc_quarantine	DMARC policy p=quarantine	+
dmarc_none	DMARC record with p=none (monitoring only)	+ weak
no_spf_no_dmarc	Neither SPF nor DMARC published, which is common for throwaway and parked domains	−
dkim_google	A Google DKIM key at google._domainkey, which reveals Workspace even behind a mail gateway	+ ; Workspace evidence
txt_saas_tokens:N	Domain-verification TXT tokens for business SaaS (Atlassian, DocuSign, Slack, Zoom, Adobe, Stripe, Microsoft MS=, Facebook, Apple…). Suffix :n = how many.	+

Microsoft tenant

Code	Meaning	Effect
ms_tenant	The domain belongs to a Microsoft Entra ID tenant (found through Microsoft’s public OpenID discovery); tenant_id is filled	+ ; Microsoft 365 evidence
ms_federated	The tenant federates sign-in to another identity provider (Okta, ADFS, Ping…); see identity_provider	+

Domain enrichment

Set with deep=true, or when the domain was already enriched in the background.

Code	Meaning	Effect
new_domain	Registered less than 30 days ago (RDAP); sets is_new_domain	− strong
young_domain	Registered less than 180 days ago (RDAP)	−
parked_domain	The homepage is a parking or “for sale” page	− strong
no_website	No homepage answered within the time limit	−
has_website	A homepage answered	+ weak

Crowd and operations

Code	Meaning	Effect
crowd_shared_suspected	Many distinct people across many unrelated customer accounts use this domain, which looks like a shared provider. Sent to human review; it never flips the category by itself.	info, −
dns_timeout	DNS lookups timed out; the verdict comes from lists only and degraded is true	info, −
dns_servfail	The domain’s own DNS servers failed (SERVFAIL/REFUSED), so it can’t receive mail right now	→ invalid

Using reasons in your code

const codes = result.reasons.map((r) => r.split(':')[0]);

if (codes.includes('typo_suspected') && result.did_you_mean) {
  showHint(`Did you mean ${result.did_you_mean}?`);
}
if (codes.includes('ms_tenant')) {
  preselectConnector('microsoft');
}

See also: Response fields · Workspace detection · Categories and policies