Real-time email validation
Real-time validation analyses an address while a person is typing it, and returns a status in the response to the call. Of the twenty checks, nineteen run without consuming a credit, so every keystroke can be validated at no cost. SMTP verification stays optional and is requested at the moment that matters.
valid
- Syntax Syntax is valid valid
- Domain MX records found valid
- SMTP mailbox Mailbox accepted valid
- Disposable domain Not listed as disposable valid
credits.used = 1: only SMTP verification is charged.One call, one decision
A request carries one address, and the response comes back in the same call. With no extra parameter, only the free checks run and no credit is charged, whatever the result. This is the form to use to validate an entry as it is typed, on a high traffic form.
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]"}' Adding the SMTP verification parameter to this same request starts the dialogue with the receiving server. It is the only change that can lead to a charge.
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}' 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.
Which decision to take for each status
Four statuses, four different courses of action. The valid status lets the journey continue. The invalid status justifies a refusal: the address will bounce. The risky status calls for a business rule rather than an automatic refusal. The unknown status must never block a sign-up: it describes a server, not an address.
| Status | What it means | Course of action |
|---|---|---|
| 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. |
When to request SMTP verification
Validate on every keystroke without SMTP verification, then request SMTP verification once only, when the form is submitted. This sequence gives an immediate correction of typing mistakes without spending a credit, and keeps the charged check for the moment the address is actually stored in the database.
A credit is charged if and only if SMTP verification was requested and the final status is not "unknown".
- As the address is typed. The 19 free checks detect faulty syntax, a domain with no mail server, a disposable address and a domain typo, with its suggested correction.
- On submission. SMTP verification confirms or rules out the existence of the mailbox. This is the moment a credit can be charged.
- Never twice. An address already verified does not need to be verified again in the same session.
The time granted to the SMTP session can be set, between 1,000 and 30,000 milliseconds: you adjust it to your journey.
Validation designed for typing
Without SMTP verification, the response depends only on fast checks and arrives straight away: every keystroke can be validated without getting in the way of typing. SMTP verification, for its part, is requested when the form is submitted, when the address is actually stored.
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.
Frequently asked questions
- Should SMTP verification be switched on in a sign-up form?
- Not systematically. The nineteen free checks already rule out invalid syntax, a domain with no mail server, a disposable address and a domain typo. SMTP verification is worth it when the cost of a wrong address exceeds the cost of a credit, for instance on a quote request form.
- What should I do when the status returned is unknown?
- Accept the entry and do not block the person. An unknown status describes a server that did not make a verdict possible, not a wrong address. Refusing a sign-up on that ground turns away real customers, and the call is not charged anyway.
- Is validation fast enough for a form?
- Yes. Without SMTP verification, the response is immediate, ideal for validating as the person types. With SMTP verification, it arrives as soon as the receiving server has answered, and the maximum time is set on each call. The right reflex: validate without SMTP as the address is typed, then request SMTP verification when the form is submitted.
- Is a message sent to the address being verified?
- No. SMTP verification opens a session with the receiving server and stops before writing the message. The person whose address is verified receives nothing, and nothing appears in their mailbox.
Going further
The API reference page brings together the parameters, the response codes and the detail of the checks. To validate a form without writing integration code, the widget calls the same engine from the page. To clean an existing base, batch processing applies the same billing rules.