Skip to main content

Quick start

From creating your account to reading your first verdict, in four steps.

1. Create an API key​

  1. Create an account on app.yeswecheck.fr. The Free plan includes 100 welcome credits, no card required.
  2. Open API keys in the dashboard menu, then create a key. Only the organisation's owner and admin roles can do this.
  3. Choose the active checks. SMTP is disabled by default: enable it if you want to confirm that mailboxes exist (1 credit per conclusive verification).
  4. Copy the key straight away: it is only shown once.

Store it in an environment variable on your server, never in your code or in a web page:

.env
YWC_API_KEY=ywc_live_xxxxxxxxxxxxxxxxxxxxxxxx
Test without spending

A key without SMTP uses no credits: syntax, DNS, disposable addresses, typos and trap domains are free. There is no separate sandbox environment; a ywc_test_… key behaves exactly like a ywc_live_… key and only serves to keep your uses apart.

2. Verify an address​

curl https://api.yeswecheck.fr/v2/email/validate \
-H "Authorization: Bearer $YWC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]"}'

The request body contains only the address. The optional fields (country, smtpTimeout) are described in the reference; any unknown field is rejected with a 400 error.

3. Read the response​

An excerpt from a response, with a key that has SMTP enabled and a mailbox that exists:

{
"result": "valid",
"score": 100,
"freeProvider": true,
"businessEmail": false,
"disposable": false,
"alias": false,
"finalDecision": "accepted",
"features": {
"syntax": { "result": "valid", "score": 100, "message": "…", "details": { "normalizedEmail": "[email protected]" } },
"dns": { "result": "valid", "score": 100, "reasonCode": "MX_FOUND", "message": "…" },
"smtp": { "result": "valid", "score": 100, "reasonCode": "MAILBOX_EXISTS", "message": "…" },
"disposable": { "result": "valid", "score": 100, "message": "…" },
"typoDomain": { "result": "valid", "score": 100, "message": "…" }
},
"metadata": {
"requestId": "0192f6b4-…",
"timestamp": "2026-10-15T09:12:44.512Z",
"processingTime": 1840,
"credits": { "used": 1, "remaining": 4819 },
"apiVersion": "2.0"
}
}

Three fields are enough to decide:

FieldContent
resultThe verdict: valid, risky, invalid or unknown.
scoreConfidence, from 0 to 100.
warningsOnly present if a risk signal was found (disposable, typo, trap domain…).
The verdict is called result

An older version of this documentation mentioned a status field and typo, smtp.deliverable or metadata.creditsUsed blocks. They never existed in API v2.

Each field is described in detail in Anatomy of the response.

4. Decide​

VerdictMeaningRecommended action
validDeliverable address, with no notable risk signalAccept
riskyDeliverable but risky: disposable, trap or malicious domain, noreply address, or score below 70Accept with caution, or reject depending on your context
invalidInvalid syntax, domain with no mail server, mailbox rejected by SMTP, or address on the blocklistReject
unknownThe server did not allow a conclusion: accept-all domain, greylisting, timeoutAccept with caution; no credit is charged

The Verdicts and score page explains how each verdict is reached.

What next​