Data catalog · Waterfall
Send one address and get back a verdict: whether it is valid, whether the domain is disposable, whether an MX record exists, and a status label you can branch on. Runs a provider waterfall. If the waterfall cannot reach a verdict, the call bills zero credits.
Last updated September 22, 2026
One address in, a verdict out. `POST /email_verifier` tells you whether the mailbox is real, whether the domain is a disposable throwaway, and whether it can receive mail at all. **[Get 25 free credits — no card](https://app.richapi.ai)**
Verification vendors hand you a single word and expect you to trust it. This endpoint returns the verdict plus an `execution_log`: which providers ran, in what order, and what each one said. When two vendors disagree about an address, you can see the disagreement instead of averaging it in the dark. ```json { "success": true, "result": {}, "provider": "provider", "providers_tried": 2, "execution_log": [ {"provider": "provider", "status": "no_data"}, {"provider": "provider", "status": "success"} ] } ``` Provider names are redacted. The only statuses shown here are `success` and `no_data`. A miss uses the same envelope with `"success": false`, `"result": null`, `"provider": null`, and `"billed": false`. That miss bills zero credits. `execution_log` is the waterfall receipt; it is not listed on the public OpenAPI schema, so treat this as the envelope shape, not a contract you code against. `email_verifier` is a waterfall endpoint. Billing is on 2xx, and a waterfall response carrying `success: false` bills zero credits with `billed: false` in the body. If the providers ran and none of them could reach a verdict, that call is free.
The request body is one field: `email`. It is validated against `^[^\s@]+@[^\s@]+\.[^\s@]+$` before anything else happens, so a malformed address fails fast as a 4xx and costs you nothing. The response splits the answer into parts you can branch on rather than one opaque score: - `valid` — the boolean verdict - `status` — the verdict label, which is the field to write suppression rules against - `disposable` — true for throwaway and burner domains - `mxFound` — whether the domain has a mail exchanger at all `mxFound: false` is the cheapest signal in the set. A domain with no MX record cannot receive mail from anyone, ever, so those rows leave your list before you argue about anything else.
A catch-all domain accepts mail addressed to anything at all. `ceo@`, `jane@`, `asdfgh@`, all accepted at the SMTP handshake and all indistinguishable. No verifier on earth can prove a specific mailbox exists behind one, because the server does not distinguish between them. What separates vendors is what they do with that. Some return `valid: true` and let you learn the truth from your bounce rate. Others return `valid: false` and silently delete a chunk of real, reachable prospects from your list, and catch-alls are common at exactly the mid-market and enterprise domains you want. A few charge full price for a verification that verified nothing. This endpoint labels the outcome instead of picking a side for you, and the `execution_log` shows which providers reached that conclusion. The live OpenAPI types `status` as a string and ships the placeholder `"example"`. Do not code against a published enum. Branch on `status` rather than on `valid` alone. Send to catch-alls on a separate track with a warmer sending domain and a tighter volume cap, rather than treating them as either safe or dead.
**1. Get a key.** Sign up at [app.richapi.ai](https://app.richapi.ai). 25 free credits, no card. **2. Post the address.** ```bash curl -X POST https://api.richapi.ai/api/v1/email_verifier \ -H "x-api-key: $RICHAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "jane@acme.com"}' ``` **3. Read the verdict.** ```json { "email": "jane@acme.com", "valid": true, "status": "deliverable", "disposable": false, "mxFound": true } ``` The live OpenAPI types `status` as a string and ships the placeholder `"example"`. Do not code against a published enum. **4. Branch on the fields, in this order.** Drop on `mxFound: false`. Drop on `disposable: true` if you are doing B2B. Then route on `status`, keeping catch-alls on their own track. **5. Or verify from your agent.** The [hosted MCP server](/integrations/claude) exposes `email_verifier` as a tool in Claude, Cursor, Windsurf and VS Code with no install: ``` Verify jane@acme.com and tell me whether it's safe to send to. ```
Verification is the cheapest call in the chain and the one people run in the largest volume, so per-request billing quietly turns list hygiene into a recurring tax on rows you were going to delete anyway. Here the billing is on 2xx, and a waterfall call where the providers ran without producing a verdict carries `billed: false` and costs zero. You pay for verdicts, not attempts. On a list where a slice of rows are dead domains and dead providers, that difference compounds every time you re-clean the same database.
| Field | Type | What it is | |---|---|---| | `email` | string | The address you submitted, echoed back | | `valid` | boolean | The deliverability verdict | | `status` | string | The verdict label to branch on | | `disposable` | boolean | True for throwaway and burner domains | | `mxFound` | boolean | Whether the domain has an MX record | | `execution_log` | array | Every provider tried and what each returned | | `billed` | boolean | Present on a miss, always `false` |
`email_verifier` bills a flat `2 credits` per successful call. A call with no verdict bills zero. Credits are prepaid. No seats, no subscription, no contract. The per-credit rate varies by package tier, so take your rate from [the pricing page](/pricing) rather than assuming one number applies to everyone.
**Guarding a cold-send domain.** Bounce rate is what gets a sending domain throttled, and it is the one input you fully control. Verify immediately before the send rather than at import time. An address that verified clean eight weeks ago belongs to someone who may have left the company since. **Cleaning an inherited database.** You take over a CRM with a few hundred thousand contacts of unknown provenance. Run the whole thing through, delete on `mxFound: false`, quarantine on `disposable: true`, and you have a defensible list without paying to re-verify rows that never had a chance. **Gating a signup form.** Call the verifier server-side when someone submits a trial signup and reject disposable domains at the door. This is one call on the request path, and `disposable` is the only field you need to read.
Most verification APIs bill on every address you submit. See [Hunter.io as the email-stack comparison](/alternatives/hunter) for what changes when a waterfall miss bills zero and every call returns its own audit trail.
- [Email finder API](/api/email-finder) — get the address, then verify it here - [Phone number finder API](/api/phone-finder) — the same waterfall billing, for mobile numbers - [All endpoints](/api) — the full catalog - [Pricing](/pricing) — credit packages and tier rates - [Search, find, verify — the chain](/use-cases/list-build-and-verify) - [Catch-all handling](/use-cases/catch-all-email-handling)
**What am I charged for?** Verdicts. `email_verifier` is a waterfall endpoint, so a 2xx carrying `success: false` bills zero credits and says `billed: false`. Malformed addresses fail the regex as a 4xx and also cost zero. **Is `valid: true` a guarantee the message lands?** No, and no verifier can give you one. It means the mailbox checks out at verification time. Inbox placement depends on your sending reputation, your content and the recipient's filters, none of which this endpoint sees. **How do I handle catch-all domains?** Branch on `status`, not on `valid`, and give catch-alls their own sending track with lower volume. Nothing can confirm an individual mailbox behind a catch-all server. **How fresh is the result?** Each call checks at request time. Mailboxes are deactivated constantly, so verify close to the send rather than storing a verdict and reusing it months later. **Can I call this from Claude or Cursor (MCP)?** Yes. The hosted MCP server exposes `email_verifier` as a tool with a copy-paste config and no install. **Do I need a credit card?** No. 25 free credits on signup, no card.
Verify your first address in two minutes. **[Get 25 free credits](https://app.richapi.ai)**