Reason code catalogue
Every code that can appear in reasons[].code, transcribed fromspec/reason-codes.md, the authored source of truth. The same catalogue is served machine-readably at GET /v1/reasons.
Reason code catalogue with severity, penalty, source, trigger and example message
| Severity | Code | Penalty | Source | Trigger | Example message |
|---|---|---|---|---|---|
| High severityHigh | SYNTAX_INVALID | -100 | syntax | Address fails RFC 5322 parsing. | Address is not a syntactically valid email. |
| High severityHigh | DISPOSABLE_DOMAIN | -60 | allowlist:disposable | Domain itself is on the maintained disposable-domain list (e.g. mailinator.com). | mailinator.com is a known disposable email domain. |
| High severityHigh | DISPOSABLE_MX | -60 | dns:mx + allowlist:disposable | Domain's MX record resolves to a disposable-mail provider's mail servers, even though the domain itself isn't listed. | MX for this domain points at a known disposable mail provider. |
| High severityHigh | NO_MX | -60 | dns:mx | Domain has no MX record and no fallback A/AAAA usable for mail. | Domain has no MX record; it cannot receive mail. |
| High severityHigh | DOMAIN_NOT_RESOLVING | -60 | dns | Domain does not resolve at all (NXDOMAIN / SERVFAIL). | gmial.com does not resolve. |
| High severityHigh | SPAM_TRAP | -100 | heuristic:spamtrap | Address matches known spam-trap patterns/signatures. | Address matches a known spam-trap pattern. |
| High severityHigh | MAILBOX_UNDELIVERABLE | -60 | smtp | Live SMTP probe (paid deliverability check) returns a hard bounce (5xx, mailbox does not exist). | SMTP server reported this mailbox does not exist. |
| High severityHigh | CUSTOM_BLOCKLIST | -100 | list:custom | Email or domain matches an entry in the customer's own block list. | Address is on your custom block list. |
| Medium severityMedium | ROLE_ACCOUNT | -20 | heuristic:role | Local part matches a known role/functional alias (admin, support, sales, noreply, …). | support@ is a shared role account, not a personal mailbox. |
| Medium severityMedium | CATCH_ALL | -15 | smtp | Live SMTP probe shows the domain accepts mail for any local part. | Domain accepts mail for any address (catch-all); this address could not be individually verified. |
| Medium severityMedium | DOMAIN_NEW | -15 | rdap | RDAP registration date is under 30 days old. | Domain was registered 6 days ago. |
| Medium severityMedium | TYPO_SUSPECTED | -20 | heuristic:typo | Local/domain part is within edit-distance 1-2 of a well-known free provider. | Did you mean [email protected]? |
| Medium severityMedium | GIBBERISH_LOCAL_PART | -15 | heuristic:entropy | Local part scores above the entropy/consonant-run threshold for human-generated text. | Local part looks machine-generated rather than a human name. |
| Medium severityMedium | ABUSE_REPORTED | -25 | feed:abuse | Address or domain appears in FWC's abuse-report feed within the retention window. | This address has been reported for abuse in the last 90 days. |
| Low severityLow | NO_SPF | -5 | dns:spf | Domain has MX but no SPF TXT record. | Domain has no SPF record. |
| Low severityLow | NO_DMARC | -5 | dns:dmarc | Domain has no DMARC TXT record. | Domain has no DMARC record. |
| Low severityLow | DMARC_NONE | -5 | dns:dmarc | DMARC record exists with p=none. | DMARC policy is 'none' (monitor-only, not enforced). |
| Low severityLow | STALE_RESULT | -3 | cache | Result served from cache with cache.age_seconds > 86400. | Result is from cache and is over 24 hours old. |
| Info severityInfo | FREE_PROVIDER | 0 | allowlist:freemail | Domain matches the maintained free-webmail list. | gmail.com is a well-known free mailbox provider. |
| Info severityInfo | SUBADDRESS | 0 | syntax | Local part contains a +tag (or provider-specific separator) that normalization strips. | Plus-addressing detected; normalized form removes the tag. |
| Info severityInfo | ALLOWLISTED | +5 | allowlist:freemail / allowlist:esp | Domain matches FWC's own curated allowlist. | Domain is on FWC's verified-sender allowlist. |
| Info severityInfo | CUSTOM_ALLOWLIST | +5 | list:custom | Email or domain matches an entry in the customer's own allow list. | Address is on your custom allow list. |
| Info severityInfo | EDUCATION_DOMAIN | 0 | heuristic:tld + provider | Domain TLD/registry class resolves to education (.edu, national equivalents). | university.edu is an educational institution domain. |
| Info severityInfo | GOVERNMENT_DOMAIN | 0 | heuristic:tld + provider | Domain TLD/registry class resolves to government (.gov, national equivalents). | agency.gov is a government domain. |
low and info reasons never change the verdict. Onlyhigh forces reject and medium forcesreview when no high reason is present.