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.

  1. Create a key

    A free account gives you an API key and 100 free SMTP checks, with no credit card.

  2. Send the address

    One POST /v2/email/validate call, with the header Authorization: Bearer. The smtp parameter decides whether the charged verification runs.

  3. Decide on the status

    The result field says what to do with the address. The score and 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.

Request
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.
Response
{
  "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?

The server: the mailbox

Only the recipient's server knows whether the mailbox exists.

Only charged stage: 1 credit, and only if the status reaches a verdict

A single response resultvalid score100 featuresthe detail of every check

The 20 checks, arranged by the part of the address they examine, with their field in the API response. The free checks run together; SMTP verification then queries the recipient's server, and it is the only one that can cost a credit.

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.

The 5 parameters accepted by the validation call.
ParameterTypeEffect
emailstring, requiredAddress to analyse.
smtpboolean, optionalRequests SMTP verification of the mailbox. This is the only parameter that can lead to a credit being charged.
enrichmentboolean, optionalRequests identity enrichment: first name, last name, gender and presumed age inferred from the local part.
smtpTimeoutinteger, optionalMaximum time granted to the SMTP session, in milliseconds. The server refuses a value outside the accepted bounds.
countrystring, optionalReference 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.
The 3 public endpoints, called with an API key or by the widget.
CallRole
POST /v2/email/validateValidate one address and receive the detail of every check.
GET /v2/widget/configPublic configuration of a widget, read by the embedded script.
POST /v2/widget/validateValidation 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.

See how real-time validation works

Batch processing

Import as CSV or TXT, up to 500,000 rows and 15 megabytes per file. Export as CSV, XLSX, PDF.

See how a batch job runs

Form widget

The same engine, called from a form, without writing any integration code and without exposing a key in the page.

See how to add the widget to a form

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.

Understand SMTP verification

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.

The 4 statuses, their definition and the decision they call for.
StatusDefinitionDecision
validThe 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.
invalidThe 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.
riskyThe 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.
unknownThe 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.

Read the definition of the statuses and the score

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.

The 5 response codes an integration has to handle.
CodeSituationWhat to do about it
200SuccessValidation completed, the body carries the full result.
401Not authenticatedThe Authorization header is missing, malformed, or the key has been revoked.
402Out of creditsSMTP verification was requested while the balance is empty. The other checks stay available by dropping the smtp parameter.
422Invalid requestA parameter does not respect its type or its bounds. The body lists the offending fields.
429Cap reachedThe 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".

The 3 monthly plans, in euros excl. VAT.
PlanMonthly priceSMTP checks included
FreeFreeNo allowance, credits bought in packs
Starter€29 excl. VAT25,000 per month
Pro€99 excl. VAT100,000 per month
The 5 cases in which no credit is charged.
CaseWhat the engine does
SMTP verification was not requestedThe call carries "smtp: false". The other nineteen checks run with no quota.
The address is on the organisation's allow listSMTP is skipped, the list decides.
The address is on the organisation's block listSMTP 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 modeAudit 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.

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.