Email Verification API Guide: Integrate Verification in Minutes

An email verification API lets your application check whether an address is deliverable before you ever try to send to it. Instead of maintaining your own list of disposable domains, MX-record lookups, and syntax rules, you send an address to an endpoint and get back a clear verdict you can act on. This guide walks through integrating the ClearMX API end to end: authenticating with a bearer token, making a request to POST /api/v1/verify, reading the response fields, and deciding what to do with the result.

The whole point is to catch bad addresses at the moment they enter your system: on a signup form, in a CSV import, or inside a background job that scrubs an existing list. Doing that at the edge keeps your sender reputation clean and your database honest. If you just want to try the checks by hand first, the free email verifier runs the same logic in the browser with no code.

Authentication

Every request is authenticated with an API token passed in the Authorization header as a bearer token. You generate a token from your account dashboard after signing up. Keep it server-side. Because a token spends your verification credits, it should never be exposed in client-side JavaScript, mobile bundles, or committed to a repository.

The header looks like this on every call:

Authorization: Bearer <your_api_token>

If the token is missing or invalid, the API returns an authentication error rather than a verification result, so handle that case separately from a normal response.

Making a verification request

The core endpoint is POST /api/v1/verify. It accepts a JSON body containing the address you want to check and returns a JSON verdict. The call is synchronous: you send one address, you get one result back in the same response. That makes it easy to call inline during a signup flow or a form submission.

The request

Send a JSON body with a single email field, along with your bearer token and a JSON content type:

POST /api/v1/verify
Authorization: Bearer <your_api_token>
Content-Type: application/json

{ "email": "casey@example.com" }

The response

The response is a JSON object describing the verdict, a numeric score, the specific reason behind it, a breakdown of individual checks, and how many credits the call consumed. Conceptually it looks like this:

{
  "result": "deliverable",
  "score": 100,
  "reason": "mailbox_exists",
  "checks": {
    "syntax": true,
    "mx": true,
    "disposable": false,
    "role": false,
    "free": false,
    "accept_all": false,
    "smtp": { "status": "ok" }
  },
  "credits_used": 1
}

The checks object carries several more fields than shown here — the API reference lists the full set.

Reading result, score, and checks

Three fields carry most of the signal: result, score, and checks.

result

The result field is the headline verdict and takes one of four values:

• deliverable — the address passed the checks and the mailbox itself was confirmed at the mail server.
• risky — the address is technically valid but carries a signal worth weighing: a disposable domain, a catch-all domain, a role account, or a mailbox that could not be confirmed.
• undeliverable — the address failed a hard check: broken syntax, a domain with no MX records, or a mailbox the server rejected outright.
• unknown — the check could not reach a confident conclusion, typically greylisting, a timeout, or a DNS failure.

score

The score is a 0-100 confidence value. Branch on result first and treat the score as a tie-breaker within a result, because the two are not interchangeable: unknown is decided before the score bands are consulted and comes back with a mid-range score of its own, so code that reads the score alone would reject a merely greylisted mailbox as undeliverable. Among the three decided results the bands are 80 and above for deliverable, 50 to 79 for risky, and below 50 for undeliverable — useful when you want a stricter or looser line than the default. A conservative signup flow might accept only deliverable, while a re-engagement campaign might also take risky above a score you pick.

checks and reason

The checks object exposes the individual signals behind the verdict: RFC-aware syntax, domain and MX/DNS resolution, disposable-domain matching, role-account detection (info@, support@, and similar), free-provider identification, and catch-all/accept-all detection. An SMTP mailbox check talks to the mail server as well, wherever the receiving side allows it — it is not a paid tier, and the call costs the same single credit whether the probe ran or not. Importantly, ClearMX never sends a message; the SMTP step stops before any email is delivered.

The reason field names the single most significant factor, with values like mailbox_exists, no_mx, disposable_domain, mailbox_unconfirmed, or role_account. Log it. When you later ask why an address was rejected, the reason is the answer.

Acting on the result

A verdict is only useful if your code does something with it. A common pattern:

1. deliverable — accept the address and continue as normal.
2. risky — read the reason before you decide, because this bucket is not one thing. disposable_domain is a throwaway inbox and is usually worth rejecting outright, even though it is not an undeliverable verdict. role_account and accept_all often work but carry lower engagement, so you may want to keep them out of cold-outreach segments. mailbox_unconfirmed just means nobody would confirm the mailbox for us — accept it and flag it.
3. undeliverable — reject at the form with an inline error, or drop the row from an import.
4. unknown — do not block the user on a transient failure. Accept provisionally and re-check later, or fall back to your normal flow.

Because the endpoint is synchronous, wrap it in your own timeout and treat a network failure the same as unknown so a slow lookup never blocks a signup. For deeper background on the underlying signals, see the MX record checker and the disposable email checker.

Real-time versus bulk

Use the API when you need an answer in the moment: validating a signup, an in-app form, or a webhook payload. When you already have a list, don't loop the single-address endpoint thousands of times. Instead use bulk email verification: upload a CSV, let ClearMX verify every row in the background, and export a clean, deliverable-only list. It's the right tool for cleaning an existing database or a newsletter list before a send.

Getting started

API access is included on every account. ClearMX prices verifications as pay-as-you-go credits in EUR, and credits never expire — no subscription required and no monthly reset. (An optional monthly plan tops credits up at 20% less per credit if steady volume suits you; those roll over too.) New accounts start with 500 free verification credits, no card required, which is enough to wire up the integration and test it against real addresses. Buying a larger batch of credits at once lowers the price per verification as you grow. See pricing for the full breakdown, browse the other guides for related workflows, or create an account to generate a token and make your first call.