Email verification API hosted in Europe
The YesWeCheck email verification API analyses an address and returns a status, the reasons behind it and a risk score. Twenty checks run on every address, nineteen of them without consuming a credit. SMTP verification is the only charged check. Data is hosted in France, with OVHcloud.
This page brings together the functional reference of the API: what it measures, what it returns and what it charges. The full schemas, the detailed error codes and the examples for each language live in the documentation.
Integrate the API in three steps
An integration comes down to three moves: get a key, send the address to the validation endpoint, then decide on the status returned. The score and the detail of the checks then help refine the decision, or explain a refusal to the person typing the address.
-
Create a key
A free account gives you an API key and 100 free SMTP checks, with no credit card.
-
Send the address
One
POST /v2/email/validatecall, with the headerAuthorization: Bearer. Thesmtpparameter decides whether the charged verification runs. -
Decide on the status
The
resultfield says what to do with the address. Thescoreand the detail of the checks say why.
Authentication
Authentication goes through the Authorization header, with the Bearer scheme, for an API key as well as for a session token. The X-API-Key header is never read by the server. A live key starts with a prefix distinct from that of a test key, which makes the two environments impossible to confuse.
Authentication goes through the Authorization header, with the Bearer scheme, for an API key as well as for a session token. The X-API-Key header is never read.
curl -X POST https://api.yeswecheck.fr/v2/email/validate \
-H "Authorization: Bearer $YESWECHECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","smtp":true}'
A live key carries the prefix ywc_live_, a test key the
prefix ywc_test_.
What the API returns
The response carries an overall status, a score and the detail check by check. Each check returns its own result, its own score and a readable message. The metadata states the number of credits charged by the call. A client can therefore decide on the status alone, or trace it back to the exact signal that produced it.
result- The overall status: the only value needed to accept, refuse or set the address aside.
score- The confidence in that status, from 0 to 100. Below 70, a valid result is returned as risky.
features- One object per check run, with its own result, its score and a readable message.
metadata.credits.used- What the call cost. Without SMTP verification, it is zero.
{
"result": "valid",
"score": 100,
"businessEmail": true,
"freeProvider": false,
"disposable": false,
"alias": false,
"features": {
"syntax": {
"result": "valid",
"score": 100,
"message": "Address is well formed."
},
"dns": {
"result": "valid",
"score": 100,
"message": "The domain announces a mail server.",
"details": {
"primaryMx": "mx.example.com",
"hasARecord": true
}
},
"smtp": {
"result": "valid",
"score": 100,
"message": "The receiving server confirms the mailbox.",
"details": {
"exists": true,
"canReceiveMail": true,
"isCatchAll": false,
"smtpCode": 250
}
},
"disposable": {
"result": "valid",
"score": 100,
"message": "Domain not in the disposable domain database."
}
},
"metadata": {
"apiVersion": "v2",
"credits": {
"used": 1
}
}
} This example shows a subset of the response: the real response carries one object per check run. Every field shown here exists in the response schema of the server, and a test verifies it every time the site is built.
The 20 checks
Every address submitted goes through twenty named checks. Nineteen run in parallel and cost nothing: syntax, DNS, disposable domains, typosquatting, role accounts, no-reply addresses, domain health. The twentieth, SMTP verification, confirms with the receiving server that the mailbox exists, and consumes a credit.
contact@example.com
Before the @: the form
Is the address well written, and does it designate a person?
- RFC 5322 syntax and normalisation
features.syntax - Role accounts
features.roleAccount - No-reply addresses, mailboxes nobody reads
features.noReply - Random local part, entropy measurement
features.randomDetection - Profanity in the local part
features.profanity - Sub-addressing and aliases
features.aliasing
Your rules
The addresses and domains your organisation allows or refuses.
- Allow list and block list of the organisation
features.listCheck
19 checks with no credit all except SMTP verification, with no quota
After the @: the domain
Can it receive mail, and does it inspire trust?
- MX records of the domain
features.dns. details. mxRecords - Fallback A and AAAA records
features.dns. details. hasARecord - Disposable domains
features.disposable - Malicious domains
features.maliciousDomains - Domain typosquatting
features.typosquat - Domain typo, with a suggested correction
features.typoDomain - Business or consumer address
businessEmail, freeProvider - SPF record of the domain
features.domainHealth. checks. spf - DMARC policy of the domain
features.domainHealth. checks. dmarc - BIMI record of the domain
features.domainHealth. checks. bimi - Domain age and registrant, through RDAP
features.domainHealth. checks. age, . registrant
The server: the mailbox
Only the recipient's server knows whether the mailbox exists.
- SMTP verification of the mailbox
features.smtp - Catch-all and accept-all detection
features.smtp. details. isCatchAll
Only charged stage: 1 credit, and only if the status reaches a verdict
A single response resultvalid score100 featuresthe detail of every check
Each check can be switched on or off on the API key: see the checks in the documentation.
Request parameters
Only one piece of information is required: the address to analyse. The other parameters switch on SMTP verification or identity enrichment, or adjust the time granted to the receiving server. Without the parameter that requests SMTP verification, the call never leads to a charge, whatever the response returned.
| Parameter | Type | Effect |
|---|---|---|
| string, required | Address to analyse. | |
| smtp | boolean, optional | Requests SMTP verification of the mailbox. This is the only parameter that can lead to a credit being charged. |
| enrichment | boolean, optional | Requests identity enrichment: first name, last name, gender and presumed age inferred from the local part. |
| smtpTimeout | integer, optional | Maximum time granted to the SMTP session, in milliseconds. The server refuses a value outside the accepted bounds. |
| country | string, optional | Reference country for the age estimate attached to a first name, as an ISO 3166-1 code. Without this parameter, the country is inferred from the domain. |
| Call | Role |
|---|---|
| POST /v2/email/validate | Validate one address and receive the detail of every check. |
| GET /v2/widget/config | Public configuration of a widget, read by the embedded script. |
| POST /v2/widget/validate | Validation called by the widget from a customer site. |
Real time and batch processing
The same engine serves two uses. In real time, a request carries one address and the response comes back in the call, which suits a sign-up form. In batch processing, a file is uploaded from the web console, processed asynchronously then returned line by line, which suits cleaning an existing base. Batch processing has no public REST endpoint.
Real time
One request, one response, the decision is immediate. This is the mode of the sign-up form and of qualifying a lead as it is typed.
Batch processing
Import as CSV or TXT, up to 500,000 rows and 15 megabytes per file. Export as CSV, XLSX, PDF.
Form widget
The same engine, called from a form, without writing any integration code and without exposing a key in the page.
The same engine from ChatGPT, Claude or Le Chat, in conversation
SMTP verification
SMTP verification opens a session with the receiving server, announces the sender and the recipient to it, then stops before writing the message. No mail arrives in the mailbox being analysed. It is the only charged check, and it is only charged when the server actually makes a verdict possible.
SMTP verification opens a session with the receiving server, announces the sender and the recipient, then stops before writing the message. No mail arrives in the mailbox being analysed, and the person whose address is verified receives nothing.
When the SMTP probe actually talked to the server, its result prevails. The other checks can degrade a result to risky, they can never turn a refusal by the server into an acceptance.
Score and statuses
Every address receives one status among four and a score from zero to one hundred. The status says what to do with the address, the score says with what confidence. A technically acceptable result whose score falls below the degradation threshold is returned as risky rather than valid.
| Status | Definition | Decision |
|---|---|---|
| valid | The address exists and the receiving server agrees to accept it. When SMTP verification is requested, this status is only returned if the server confirmed the mailbox. | Accept the address. |
| invalid | The address cannot receive mail: malformed syntax, a domain with no MX record, a mailbox refused by the server, or an address present in the block list of the organisation. | Reject the address, it will produce a hard bounce. |
| risky | The address is technically acceptable but carries a risk signal: disposable domain, malicious domain, typosquatted domain, no-reply address, or an overall score below the degradation threshold. | Accept under conditions, or discard according to the configured business policy. |
| unknown | The receiving server gives no definitive answer, for instance on a catch-all domain or during a greylisting delay. The reason is named in the response. | Decide according to context. No credit is charged. |
The score is returned on a scale from 0 to 100. Below 70, a technically valid result is downgraded to a risky result.
Response codes to handle
A robust integration distinguishes four situations to handle: the token refused, the credit balance to top up, the parameter out of bounds and the key cap reached. Each one calls for a simple, documented action. An empty balance, in particular, leaves the nineteen free checks available.
| Code | Situation | What to do about it |
|---|---|---|
| 200 | Success | Validation completed, the body carries the full result. |
| 401 | Not authenticated | The Authorization header is missing, malformed, or the key has been revoked. |
| 402 | Out of credits | SMTP verification was requested while the balance is empty. The other checks stay available by dropping the smtp parameter. |
| 422 | Invalid request | A parameter does not respect its type or its bounds. The body lists the offending fields. |
| 429 | Cap reached | The cap of the API key has been reached. The body states which window is concerned. |
Where addresses are processed
YesWeCheck hosts its data in France, with OVHcloud. No message is sent to the recipient during verification. Stored addresses are encrypted at rest.
Data hosted in France, by OVHcloud.
What a call costs
The cost structure fits in one sentence: a credit is charged if and only if SMTP verification was requested and the final status reaches a verdict. The other nineteen checks run with no quota. A hundred SMTP checks are offered once, at sign-up, with no credit card.
A credit is charged if and only if SMTP verification was requested and the final status is not "unknown".
| Plan | Monthly price | SMTP checks included |
|---|---|---|
| Free | Free | No allowance, credits bought in packs |
| Starter | €29 excl. VAT | 25,000 per month |
| Pro | €99 excl. VAT | 100,000 per month |
| Case | What the engine does |
|---|---|
| SMTP verification was not requested | The call carries "smtp: false". The other nineteen checks run with no quota. |
| The address is on the organisation's allow list | SMTP is skipped, the list decides. |
| The address is on the organisation's block list | SMTP is skipped, the list decides. |
| The final status is "unknown" | In real time, nothing is charged. In batch processing, these addresses are credited back automatically when the file is closed. |
| The file is processed in audit mode | Audit mode charges no credit, including for the sample it checks over SMTP. |
Credits bought in packs never expire. The monthly credits of a subscription do not roll over from one month to the next.
100 SMTP checks are credited once at sign-up. The 19 other checks never consume a credit.
Clear answers, even in the hard cases
Some servers do not let you decide: a domain that accepts every address, or a server that delays its answer. The API does not guess on your behalf: it returns an unknown status, names the reason and charges nothing. You decide with full knowledge, and you only pay for useful answers.
- Catch-all domains. A domain configured to accept every address is spotted and reported in the response. The status returned is unknown, and no credit is charged.
- Delays. A server that asks to come back later gets an unknown status rather than a guessed verdict, with no charge. In batch processing, a second pass goes back for the firm answer.
- A base that stays up to date. Revalidating a list before every major campaign takes a few clicks, and the free checks consume no credit.
- Response time. Without SMTP verification, the response is immediate. With SMTP verification, it arrives as soon as the receiving server has answered, and the maximum time allowed is set on each call.
Get started
Creating an account is enough to get an API key and a hundred free SMTP checks. No credit card is asked for. The documentation publishes the response schemas, the error codes and the integration examples for each language. As long as SMTP verification is not requested, no credit is consumed.