Email Verification API: How It Works, With Code Examples

Uploading a CSV works when you clean a list once in a while. But if addresses enter your system every day (sign-up forms, checkout pages, a CRM, an internal tool), you want to check them the moment they arrive. That is what an email verification API is for: your code sends an address, and a second later it gets back a verdict it can act on.

This article explains what happens behind that call, what the response contains, and how to use it well, with working examples.

What an email verification API does

You send one HTTP request with an email address. The service then runs the same checks a mail server would, without sending any email:

1. Syntax: is the address correctly formed?
2. Domain and DNS: does the domain exist?
3. MX records: does the domain have mail servers? (Try it with our MX lookup.)
4. Mailbox (SMTP): the service connects to the domain's mail server, asks whether it accepts mail for this address, and disconnects before any message is sent.
5. Catch-all: it asks about a random address on the same domain. If that one is accepted too, the domain accepts everything and the mailbox cannot be confirmed (more on catch-all domains).
6. Risk signals: disposable domains, role addresses, typos in popular domains, and signs of spam traps.

It returns a structured result your code can use to accept, reject or flag the address.

Where to use it

• Sign-up and contact forms: stop fake and mistyped addresses before they reach your database, and suggest the fix for typos (gmial.com → gmail.com).
• Checkout: make sure the order confirmation and receipt can be delivered.
• CRM imports and enrichment: verify contacts as they are created or updated.
• Before a send: check a segment that has not been mailed for a while.

For whole files, a bulk endpoint is better than thousands of single calls (see how to verify a list in bulk).

Your first request

With MailQuell, create an API key in Developer Hub → API keys, then call POST /v1/verify. The key goes in the Authorization header.

cURL

export MAILQUELL_API_KEY="your API key"   # mq_live_…, from Developer Hub

curl -X POST https://api.mailquell.com/v1/verify \
  -H "Authorization: Bearer $MAILQUELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "creditType": "auto"}'

JavaScript (Node.js 18+ or the browser of your own back office)

const res = await fetch('https://api.mailquell.com/v1/verify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILQUELL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'jane@example.com', creditType: 'auto' }),
});
if (!res.ok) throw new Error(`MailQuell: ${res.status}`);
const result = await res.json();
console.log(result.status, result.didYouMean);

Python

import os
import requests

res = requests.post(
    "https://api.mailquell.com/v1/verify",
    headers={"Authorization": f"Bearer {os.environ['MAILQUELL_API_KEY']}"},
    json={"email": "jane@example.com", "creditType": "auto"},
    timeout=30,
)
res.raise_for_status()
result = res.json()
print(result["status"], result["didYouMean"])

creditType: "auto" uses your plan's allowance first, then your pre-paid credits. Never put a secret API key in a public web page: call the API from your server. (For forms on a website, see the widget below.)

What the response looks like

A shortened example (the full response also has a score breakdown and the raw SMTP answer):

{
  "email": "jane@example.com",
  "status": "safe",
  "riskLevel": "low",
  "suggestedAction": "safe_to_contact",
  "score": 100,
  "technicalDetails": {
    "mailboxExists": true,
    "mxRecordsFound": true,
    "smtpCode": 250,
    "disposable": false,
    "roleAccount": false,
    "catchAll": false,
    "freeProvider": false,
    "riskSignals": []
  },
  "didYouMean": null,
  "durationMs": 526
}

The fields you will use most:

Turning the result into a decision

A simple, safe policy for a sign-up form:

• invalid or disposable: refuse the address and ask for another one.
• didYouMean is set: show "Did you mean …?" with a one-click fix. Many invalid addresses are just typos.
• risky: accept it, but flag the account for review or ask for email confirmation.
• safe, role, catch-all: accept.
• unknown: accept. Some servers refuse to answer quickly; blocking real people because of a slow server costs more than it saves.

The most important rule: never block a sign-up because the API call failed (timeout, network error, no credits left). Let the form through and verify later.

Speed, limits and errors

• Speed. Most checks take under a second, but some mail servers answer slowly. Set a timeout and do not make the user wait on it. For forms, "mode": "quick" skips the catch-all probe and answers faster.
• Rate limit. 120 requests per minute per API key. Each response carries x-ratelimit-remaining; over the limit you get 429 with a retry-after header.
• Errors. 402 means no credits left, 429 too many requests, 502 the check itself failed (the credit is returned automatically). An unknown result is not charged either.
• Large lists. Use POST /v1/bulk with up to 50,000 addresses, then get a webhook (task.completed) when the results are ready instead of polling.

No code? Use the form widget

If you only need to protect a form on your website, you do not have to write any code. MailQuell's widget is one line of HTML: it checks every email field when the visitor leaves it, offers the "Did you mean …?" fix, and stops the form for invalid and disposable addresses. It uses a public key limited to your own domains, so your credits are protected. There are ready-made guides for WordPress, Wix and Ghost.

Frequently asked questions

Does the API send an email to the address?

No. The SMTP conversation stops before the message is sent, and the person is never notified.

How much does an API call cost?

1 credit per address, catch-all check included, the same price as in the dashboard. A result that stays unknown (the mail server gave no clear answer) is free: the credit is given back. The free plan includes 200 checks every month.

Can I call the API from the browser?

Not with a secret key: anyone could read it in the page and spend your credits. Call it from your server, or use the form widget, which has a public key restricted to your domains.

Can AI assistants use it?

Yes. MailQuell also has an MCP server, so Claude, Cursor and other assistants can verify addresses with your API key in plain language.

Get started

• Try a single address with the free email checker.
• Create a free account, open Developer Hub, and make your first call in a minute.