Skip to main content

Anatomy of the response

The POST /v2/email/validate response always has the same structure: a few summary fields at the root, the details of each check in features, then the metadata.

{
"result": "risky",
"score": 52,
"freeProvider": true,
"businessEmail": false,
"disposable": true,
"alias": false,
"finalDecision": "accepted",
"policy": { "decision": "accepted", "reasons": [], "rejectedByClientConfig": false },
"warnings": [
{ "code": "DISPOSABLE_EMAIL", "severity": "warning", "message": "Disposable / throwaway email provider" }
],
"debug_ref": "YWC-7KQ2M9AB",
"features": {
"syntax": { … },
"dns": { … },
"disposable": { "result": "invalid", "score": 0, "message": "…", "reasonCode": "DISPOSABLE_DOMAIN" },
"…": { … }
},
"metadata": {
"requestId": "0192f6b4-6a1e-7c11-9d0a-3f2b8c4e1a77",
"timestamp": "2026-10-15T09:12:44.512Z",
"processingTime": 212,
"credits": { "used": 0, "remaining": 0, "breakdown": { "smtp": 0, "…": 0 } },
"apiVersion": "2.0"
}
}

The score values and message texts are given as examples.

Summary fields​

FieldTypeDescription
resultvalid · risky · invalid · unknownThe verdict. See Verdicts and score.
scoreinteger 0–100Confidence in the address.
freeProviderbooleanConsumer domain (webmail, internet service provider) or disposable.
businessEmailbooleanBusiness address: the opposite of freeProvider for a well-formed address.
disposablebooleanDisposable domain. Shortcut for features.disposable.
aliasbooleanSubaddressed address ([email protected]). Informational; does not affect the verdict.
finalDecisionaccepted · rejectedYour validation policy's decision. It only evaluates the policy's rules: an invalid address that no rule targets stays accepted.
policyobjectdecision, reasons (reject_* codes) and rejectedByClientConfig. See Policies and lists.
warningsarrayRisk signals found. Absent when there are none.
debug_refstringSupport reference for this check (e.g. YWC-7KQ2M9AB). See below.

features: the details of each check​

Each check has the same shape:

{
result: 'valid' | 'invalid' | 'unknown'; // see the callout below
score: number; // 0–100
message: string; // human-readable explanation, in English
reasonCode?: string; // stable machine code, when one exists
details?: object; // data specific to the check
}
In features, invalid means "signal detected"

For risk checks, result: "invalid" means that the signal is present: features.disposable.result === "invalid" means "disposable address", features.roleAccount.result === "invalid" means "role account". It is not the address's verdict, which stays in result at the root.

FeaturePresent ifinvalid meansUseful details
syntaxalwaysinvalid syntaxnormalizedEmail
dnsalwaysdomain with no mail servermxRecords, primaryMx, hasARecord; reasonCode: MX_FOUND, A_FALLBACK, NO_MX_NO_A, NULL_MX, DNS_ERROR
smtpSMTP enabled on the keymailbox rejectedreasonCode: MAILBOX_EXISTS, MAILBOX_NOT_FOUND, ACCEPT_ALL_DOMAIN, GREYLISTED, TIMEOUT, SMTP_INCONCLUSIVE…; details.smtpCode, details.providerDetected
catchAllaccept-all domain detected— (always unknown)reasonCode: ACCEPT_ALL_DOMAIN
disposablecheck activedisposable addressprovider
maliciousDomainscheck activemalicious domaincategory (phishing, scam_fr, blacklist…), sources
typoDomaincheck activeprobable typosuggestedDomain, suggestedEmail, detectionMethod (list, typosquat, algorithm)
typosquatcheck activetrap domain imitating a providerimpersonatedDomain (can be null)
typoCorrectionsee below—correctedDomain, correctedEmail
roleAccountcheck activerole accountpattern, category
noReplycheck activenoreply address, a mailbox nobody reads (downgrades valid and unknown to risky, except for the allowlist)kind (noreply, bounce, daemon), matchedOn (local, domain), pattern; reasonCode: NO_REPLY_DETECTED
randomDetectioncheck activerandom local partrandomnessScore
profanitycheck activeoffensive termwords, severity
aliasingcheck active— (informational)isAlias, aliasType, baseEmail
enrichmentcheck active—firstName, lastName, gender, presumedAge, presumedAgeRange, associated scores
listChecklists activeaddress on the blocklistisWhitelisted, isBlacklisted
domainHealthnon-consumer domain—label (excellent → critical), MX, SPF and DMARC checks, domain age
networkcheck active and IP known—see below

A check disabled on the key is absent from features. Syntax and DNS are always present.

Typo, trap domain and verified correction​

Three distinct signals, which can occur together:

  • typoDomain: the user probably made a mistake (gmial.com → gmail.com). details.suggestedEmail suggests the corrected address. No suggestion is made when the intended domain no longer receives mail (details.suggestionWithheld: "dead_target").
  • typosquat: the domain entered was registered to capture mail intended for a well-known provider. The message will arrive, but not to the intended person.
  • typoCorrection: with SMTP enabled, when the address entered has no reliable SMTP response (accept-all, no server, trap domain), YesWeCheck also checks the corrected address, free of charge. The block is only present if the corrected address is deliverable. The verdict, score and billing of the address entered do not change.

Priority order for suggesting a correction: typoCorrection.correctedEmail (verified), then typoDomain.details.suggestedEmail. If the address entered is valid, suggest nothing: the typo is then just information.

network: the IP calling the API​

network analyses the IP address that called the API: country, operator, Tor, VPN, hosting provider.

In a server call, that is your server

When your backend calls the API, the IP analysed is your server's, not the end user's. You will then see DATACENTER_IP in warnings on every call. Disable network on server keys, or ignore the network codes. This check only makes sense for the widget, where the call comes from the end user's browser.

warnings: the risk signals​

A machine-readable summary of everything that was found. It is descriptive: a signal being present does not imply a rejection (see finalDecision for that).

CodeSeveritySignal
DISPOSABLE_EMAILwarningDisposable address provider
TYPOSQUAT_DOMAINwarningDomain imitating a well-known provider; data.impersonatedDomain
TYPO_DETECTEDwarning, or info if the address entered is deliverableProbable typo; data.suggestedDomain
TYPO_CORRECTION_VERIFIEDinfoThe corrected address was verified as deliverable
MALICIOUS_DOMAINerrorReported domain (phishing, scam, blocklist)
ROLE_ACCOUNTinfoRole account (contact@, info@…)
NO_REPLYwarningNoreply address, to exclude from sends; data.kind
CATCH_ALL_DOMAINinfoAccept-all domain
RANDOM_LOCALPARTwarningLocal part that looks generated
PROFANITYinfoOffensive term in the local part
TOR_EXIT_NODEwarningCall from a Tor exit node
ANONYMOUS_NETWORKwarningCall from an anonymising network (VPN, proxy)
DATACENTER_IPinfoCall from a hosting provider
DUPLICATED_SUBMITTERwarningThis IP or device has submitted an unusual number of different addresses

Each entry has the shape { code, severity, message, data? }. Test code, never message.

debug_ref: the support reference​

Every single check (API, widget, customer dashboard) carries a short reference, for example YWC-7KQ2M9AB. It is for support only: a verdict surprises you, a customer disputes a rejection, an address is judged differently by another tool? Send us this reference and we can look up, step by step, how that address was processed, without you having to repeat the call.

  • Where to find it: at the root of the response, next to result. Keep it in your logs alongside the checked address if you want to be able to ask a question later.
  • Lifetime: 90 days. After that, support can no longer retrieve the details.
  • Do not build on it: it is an opaque identifier. It holds no information about the address or the verdict, and its format may change. Base your rules on result, features and warnings instead.
  • Bulk processing: the export does not include it. Give support the file name and the address concerned.

To contact us: [email protected], with the reference and the address. Never send your key.

metadata​

FieldDescription
requestIdUnique identifier of the call. Give it to support if you have a question.
timestampDate of the verification (ISO 8601, UTC).
processingTimeServer-side processing time, in milliseconds.
credits.usedCredits charged by this call: 0 or 1.
credits.remainingThe organisation's balance after the call. Only filled in when SMTP was run; 0 otherwise.
credits.breakdownBreakdown per check; only smtp can be non-zero.
apiVersion"2.0".