POST /email_verifier • Credits: 2 credits per call

The Email Verifier API checks whether one email address can receive mail. Send a POST request with the address in the email parameter. The response holds a success flag and a result object with the verification status. A call that returns a verdict costs 2 credits. A call that returns no verdict costs nothing.

What does the Email Verifier API do?

A cold email campaign burns sender reputation against dead mailboxes. The Email Verifier API checks one address before you send to it. RichAPI runs the check as a waterfall across several verification providers. The waterfall tries the providers in priority order and stops at the first provider that returns a status. The whole call has a budget of 25 seconds. One call costs the same flat credit rate, whatever the number of providers that the waterfall tries.

Which endpoint does the Email Verifier API use?

Method:POST
URL:https://api.richapi.ai/api/v1/email_verifier
Authentication:x-api-key header
Response: Synchronous JSON
Credits: 2 credits per call

How to send an Email Verifier request

Copy your API key from the RichAPI dashboard.
Set the email parameter to the address that you want to verify.
Send a POST request to https://api.richapi.ai/api/v1/email_verifier.
Send the API key in the x-api-key header.
Set the Content-Type header to application/json.
Read success and result.status from the response.
Act on the status with the table in the next section.

CAUTION: Each Email Verifier call costs 2 credits and covers one address. Verify a list one address per call, and do not verify the same address twice.

cURL

curl -X POST https://api.richapi.ai/api/v1/email_verifier   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "email": "[email protected]"
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/email_verifier",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"email": "[email protected]"},
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/email_verifier", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "[email protected]",
  }),
});

const data = await response.json();
console.log(data);

What parameters does the Email Verifier API accept?

Parameter	Type	Required	Default	Description
`email`	string	Yes	`""`	The email address to verify, for example `[email protected]`.

The Email Verifier API accepts one parameter. It verifies one address per call.

What does the Email Verifier API return?

The Email Verifier API returns status 200 for every valid request. The body holds a success flag, a result object with the verdict, and a log of the verification sources that the waterfall tried. The values below are illustrative.

{
  "success": true,
  "result": {
    "status": "valid"
  },
  "provider": "source_1",
  "providers_tried": 1,
  "execution_log": [
    { "provider": "source_1", "status": "success", "latency_ms": 640 }
  ]
}

When no source returns a verdict, success is false, result is null, and the body adds "billed": false. That call costs 0 credits.

What does each Email Verifier response field mean?

Field	Type	Description
`success`	boolean	`true` when a verification source returned a verdict.
`result`	object or null	The verdict. `result.status` holds the verification status. The value is `null` when `success` is `false`.
`provider`	string or null	A label for the source that returned the verdict, for example `source_1`. The labels number the sources in the order the waterfall tried them, within one response.
`providers_tried`	integer	The number of sources that the waterfall tried.
`execution_log`	array of objects	One entry per source tried, with `provider` (the same `source_1`, `source_2` labels), `status` and `latency_ms`.
`billed`	boolean	Present and `false` when the call returned no verdict and cost nothing.
`error`	string	Present when every source was unavailable. Send the request again after a few minutes.

What does each Email Verifier status mean?

The result.status field holds the verdict. Read the value, then take the action in the last column.

Status	What it means	What to do
`valid`	The mailbox exists and accepts mail.	Send to the address.
`invalid`	The mailbox does not exist, so mail to it bounces.	Remove the address from the send list.
`risky`	The domain grey-lists the check, so no provider confirms the single mailbox.	Keep the address out of a cold campaign, or accept a higher bounce rate.
`unknown`	No provider reached a decision for the address.	Send the request again later. If the status stays `unknown`, treat the address as `risky`.

How much does the Email Verifier API cost?

The Email Verifier API costs 2 credits per call. One credit costs $0.02 on the 1,000 and 5,000 credit packs, so one call costs $0.04 there. Larger packs cost less per credit. 1,000 calls cost 2,000 credits, and 2,000 credits cost $40.00.

Calls	Credits	Cost
1	2	$0.04
100	200	$4.00
500	1,000	$20.00
1,000	2,000	$40.00
10,000	20,000	$400.00

One call charges one flat rate. The waterfall charges no extra credit for each provider that it tries.

RichAPI charges the 2 credits only when the waterfall returns a verdict. A call with success set to false returns "billed": false and costs 0 credits. A response outside the 200 range also costs 0 credits.

What errors does the Email Verifier API return?

An error response holds an error field with a text message.

Status	Meaning	What to do
`400`	The request body failed validation.	Correct the parameter that the message names. Send the `email` parameter as a string.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	The organization has no credits left, or the team reached its monthly spend limit.	Buy credits in the RichAPI dashboard.
`403`	`Endpoint not available on your plan`: this API key has no access to this endpoint.	Call `GET /api/v1/my-endpoints` to list the endpoints this key can use. For access, write to [email protected].
`404`	The endpoint name is wrong.	Send the request to `/email_verifier`.
`405`	The request used a method other than `POST`.	Send the request again with the `POST` method.
`429`	Rate limit exceeded (too many requests per second).	Wait for the `Retry-After` seconds, then retry the request.
`500`	The API failed.	Send the request again. If the failure repeats, write to [email protected].

These codes apply to every endpoint.

When every verification source fails or times out, the API still returns 200, with success set to false, billed set to false and an error text. That call costs 0 credits. Send the request again after a few minutes.

For a retry loop, wait 1 second, then 2 seconds, then 4 seconds between attempts.

Frequently asked questions

What input does the Email Verifier API need?

The Email Verifier API needs one email address in the email parameter. An example value is [email protected].

What statuses does the Email Verifier API return?

The Email Verifier API returns one of four statuses: valid, invalid, risky or unknown. valid means deliverable, invalid means undeliverable, risky means a grey-list domain, and unknown means no decision.

How much does the Email Verifier API cost per address?

The Email Verifier API costs 2 credits per call, and one call covers one address. One credit costs $0.02 on the 1,000 and 5,000 credit packs, so 1,000 addresses cost $40.00 there.

Why does the Email Verifier API return a risky status?

A risky status means that the domain grey-lists the verification check. The domain answers the same way for a real mailbox and for a dead one, so no provider confirms the single address.

Does a failed Email Verifier call cost credits?

No. A call that returns no verdict (success is false) costs 0 credits, and so does any response outside the 200 range.

Is the Email Verifier API synchronous?

Yes. The Email Verifier API returns the verification result in the same response. No polling call and no webhook are needed.

Why does the Email Verifier API try several providers?

The Email Verifier API runs as a waterfall. It tries verification providers in priority order and stops at the first provider that returns a status. One call costs 2 credits, whatever the number of providers that the waterfall tries.

Which endpoint name does the Email Verifier API use?

The current endpoint name is email_verifier, and the path is /email_verifier. The pre-rename alias email_verify_waterfall resolves to the same endpoint. Use email_verifier for a new integration.

Can the Email Verifier API verify many addresses in one request?

No. The Email Verifier API accepts one email parameter and verifies one address per call. To verify a list, send one request per address.