Email Verification API Documentation
Complete reference for the MailValid Email Verification API. Verify email addresses in real time with syntax, domain, MX and SMTP checks.
Prefer one topic per page? Start at the Quickstart. Every docs page also has a Markdown version, and AI agents can find the full docs index at /llms.txt.
Building with an AI coding agent?
Copy one self-contained API guide and paste it into Cursor, ChatGPT, Claude or any other agent.
Fast & Reliable
Average response time under 500ms
99% Accuracy
Provider-optimized verification
Bulk Support
Up to 10,000 emails per job
https://mailvalid.io/api/v1
Authentication
Every request to https://mailvalid.io/api/v1 needs your
API key in the X-API-Key header. Keys start with
mv_live_ and belong to your account, so every call uses
your credits and your plan's limits.
Get your API key
Create a free account (100 free credits), then open Dashboard → API Keys and create a key. It is shown in full once, so copy it somewhere safe.
Check that your key works
GET /credits is free, so it is the safest first call. A
200 means the key is valid.
curl https://mailvalid.io/api/v1/credits \
-H "X-API-Key: mv_live_your_key_here"{
"balance": 100,
"lifetime_used": 0
}Authentication errors
| Status | detail | What to do |
|---|---|---|
| 401 | API key required. Include X-API-Key header. | Send the key in the X-API-Key header. |
| 401 | Invalid API key | The key is wrong, deleted or revoked. Copy it again or create a new one. |
| 401 | Invalid or expired token | You sent Authorization: Bearer …. The REST API only reads X-API-Key. |
Keep your key secret
- Call the API from your server, never from browser or mobile app code, where anyone can read the key.
- Load the key from an environment variable instead of writing it in your code or committing it to git.
- Use a separate key for each app, so you can revoke one without breaking the others.
- If a key leaks, delete it in the dashboard and create a new one. Deleted keys stop working at once.
Quickstart
Verify your first address in two minutes. Set your key as an environment variable, then run one of these:
export MAILVALID_API_KEY="mv_live_your_key_here"curl -X POST https://mailvalid.io/api/v1/verify/single \
-H "X-API-Key: $MAILVALID_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "john@company.com"}'import os
import requests
response = requests.post(
"https://mailvalid.io/api/v1/verify/single",
headers={"X-API-Key": os.environ["MAILVALID_API_KEY"]},
json={"email": "john@company.com"},
timeout=30,
)
response.raise_for_status()
result = response.json()["result"]
print(result["status"]) # valid, invalid, catch_all, unknown or do_not_mail
print(result["status_reason"]) # why, for example mailbox_confirmedconst response = await fetch("https://mailvalid.io/api/v1/verify/single", {
method: "POST",
headers: {
"X-API-Key": process.env.MAILVALID_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "john@company.com" }),
});
if (!response.ok) throw new Error(`MailValid error ${response.status}`);
const { result } = await response.json();
console.log(result.status); // valid, invalid, catch_all, unknown or do_not_mail
console.log(result.status_reason); // why, for example mailbox_confirmed<?php
$ch = curl_init("https://mailvalid.io/api/v1/verify/single");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
"X-API-Key: " . getenv("MAILVALID_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode(["email" => "john@company.com"]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
throw new Exception("MailValid error $status: " . json_encode($body["detail"] ?? $body));
}
echo $body["result"]["status"]; // valid, invalid, catch_all, unknown or do_not_mailWhat to do with the result
| status | Meaning | Suggested action |
|---|---|---|
| valid | The mailbox exists | Send |
| invalid | The address will bounce | Remove it, or ask the user to fix a typo |
| catch_all | The domain accepts every address, so the mailbox can't be confirmed | Send with care |
| do_not_mail | Disposable, role-based (info@) or a past spam complaint | Don't send marketing email |
| unknown | The mail server didn't give a clear answer. Free, 0 credits. | Retry later |
The full list of reasons is under Status Values.
Single Email Verification
Checks one address in real time: syntax, domain, MX records and the mailbox itself over SMTP, plus disposable, role-based, catch-all and free-provider flags. Most calls return in under a second. Some mail servers are slow, so set your client timeout to 30 seconds.
/api/v1/verify/single
Request body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Required | The address to check. A badly formed address is rejected with 422 and costs nothing. |
curl -X POST https://mailvalid.io/api/v1/verify/single \
-H "X-API-Key: $MAILVALID_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "john@company.com"}'import os
import requests
def verify_email(email: str) -> dict:
response = requests.post(
"https://mailvalid.io/api/v1/verify/single",
headers={"X-API-Key": os.environ["MAILVALID_API_KEY"]},
json={"email": email},
timeout=30,
)
response.raise_for_status()
return response.json()["result"]
result = verify_email("john@company.com")
if result["status"] == "valid":
print("Safe to send")
elif result["status"] == "invalid":
print("Will bounce:", result["status_reason"])async function verifyEmail(email) {
const response = await fetch("https://mailvalid.io/api/v1/verify/single", {
method: "POST",
headers: {
"X-API-Key": process.env.MAILVALID_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ email }),
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`MailValid error ${response.status}`);
return (await response.json()).result;
}
const result = await verifyEmail("john@company.com");
if (result.status === "valid") console.log("Safe to send");
else if (result.status === "invalid") console.log("Will bounce:", result.status_reason);<?php
function verify_email(string $email): array {
$ch = curl_init("https://mailvalid.io/api/v1/verify/single");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
"X-API-Key: " . getenv("MAILVALID_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode(["email" => $email]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
throw new Exception("MailValid error $status");
}
return $body["result"];
}
$result = verify_email("john@company.com");
echo $result["status"];{
"success": true,
"credits_used": 1,
"result": {
"email": "john@company.com",
"status": "valid",
"is_valid": true,
"syntax_valid": true,
"domain": "company.com",
"domain_valid": true,
"has_mx": true,
"mx_records": [
{"priority": 1, "host": "aspmx.l.google.com"},
{"priority": 5, "host": "alt1.aspmx.l.google.com"}
],
"smtp_checked": true,
"smtp_response_code": 250,
"is_disposable": false,
"is_role_based": false,
"is_catch_all": false,
"is_free_provider": false,
"confidence_score": 95,
"status_reason": "mailbox_confirmed",
"provider": "google",
"verification_time_ms": 598.7,
"cached": false
}
}Response fields
| Field | Type | Description |
|---|---|---|
success | boolean | Always true on a 200 response |
credits_used | integer | The final charge for this call: 1, or 0 for unknown |
result.email | string | The address that was checked |
result.status | string | valid, invalid, catch_all, unknown or do_not_mail |
result.is_valid | boolean | true only when status is valid |
result.status_reason | string | Why, as a code you can switch on (see Status Values) |
result.confidence_score | integer | 0 to 100. How sure the result is |
result.syntax_valid | boolean | The address is well formed |
result.domain | string | The part after the @ |
result.domain_valid | boolean | The domain exists in DNS |
result.has_mx | boolean | The domain has mail servers (MX records) |
result.mx_records | array | The domain's mail servers, each with priority and host |
result.smtp_checked | boolean | The mailbox was checked over SMTP |
result.smtp_response_code | integer or null | The mail server's reply code, for example 250 (accepted) or 550 (no such user) |
result.is_disposable | boolean | Temporary inbox provider, such as mailinator.com |
result.is_role_based | boolean | A team address such as info@, support@ or admin@ |
result.is_catch_all | boolean | The domain accepts mail for any address |
result.is_free_provider | boolean | A free mailbox provider such as gmail.com or yahoo.com |
result.provider | string or null | Detected mailbox provider, for example google, microsoft, yahoo or corporate |
result.verification_time_ms | number or null | How long the check took |
result.cached | boolean | The result came from a recent check of the same address. Billed like a fresh result. |
Fair billing
credits_used is the final charge. valid,
invalid, catch_all and do_not_mail
cost 1 credit each, fresh or cached. unknown costs
nothing, and neither does a request rejected with an error.
Bulk Email Verification
Send a list in one request and get a job ID back straight away. The
job runs in the background. Wait for it by polling the job, or pass a
webhook_url and we call you when it finishes.
- Up to 10,000 addresses per job on paid plans and 100 on Free. Over your plan's limit returns
413; over 10,000 returns422. Split bigger lists into several jobs. - Exact duplicate entries and blank entries are removed before the job starts, and are never charged.
- Badly formed addresses don't fail the job. They come back as
invalidwith reasonemail_format_invalid. - Credits for every address are reserved when you submit. Unused credits (for
unknownresults or a cancelled job) are released when it ends.
1. Submit a job
/api/v1/verify/bulk
| Field | Type | Required | Description |
|---|---|---|---|
emails | array of strings | Required | The addresses to check, 1 to 10,000 |
webhook_url | string | Optional | A URL on your server (use https) that we POST to when the job finishes. See Webhooks. |
filename | string | Optional | A label such as leads-q3.csv, shown on the job so you can recognise it. Up to 255 characters. |
source_data | object | Optional | Your own extra columns (name, company…), added back to the right of each row in the download. See Download results. |
curl -X POST https://mailvalid.io/api/v1/verify/bulk \
-H "X-API-Key: $MAILVALID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"emails": ["john@company.com", "jane@example.org", "info@business.net"],
"filename": "leads-q3.csv",
"webhook_url": "https://yourapp.com/webhooks/mailvalid"
}'{
"job_id": "03fb2d9c-39c7-4ac0-9081-8778faf5c05c",
"status": "pending",
"total_emails": 3,
"credits_reserved": 3,
"webhook_url": "https://yourapp.com/webhooks/mailvalid",
"message": "Bulk verification job created. Poll the status endpoint or wait for webhook."
}
total_emails counts unique addresses after duplicates
are removed, and credits_reserved is the most the job
can cost.
2. Wait for it to finish
/api/v1/verify/bulk/{job_id}
status moves from pending to
processing to completed (or
failed or cancelled). Poll every 5 to 10
seconds. Polling uses the separate read limit, so it never slows
down your verifications. results is null
until the job is completed or cancelled (a cancelled job returns the
addresses that finished).
{
"job_id": "03fb2d9c-39c7-4ac0-9081-8778faf5c05c",
"status": "completed",
"total_emails": 3,
"processed_emails": 3,
"valid_count": 1,
"invalid_count": 2,
"progress_percentage": 100.0,
"filename": "leads-q3.csv",
"results": [
{
"email": "john@company.com",
"status": "valid",
"is_valid": true,
"status_reason": "mailbox_confirmed",
"confidence_score": 95
// ...the same fields as a single verification result
}
],
"error_message": null,
"webhook_url": "https://yourapp.com/webhooks/mailvalid",
"webhook_delivered": true,
"started_at": "2026-10-15T07:21:41.912Z",
"completed_at": "2026-10-15T07:21:42.433Z",
"created_at": "2026-10-15T07:21:41.864Z"
}
The final charge for a job is credits_used in the
job list
and in the webhook. For files over a few thousand rows, download the
results as CSV or JSON instead of reading results.
Complete example: submit, wait, download
API=https://mailvalid.io/api/v1
JOB_ID=$(curl -s -X POST $API/verify/bulk \
-H "X-API-Key: $MAILVALID_API_KEY" -H "Content-Type: application/json" \
-d '{"emails": ["john@company.com", "jane@example.org"]}' | jq -r .job_id)
while true; do
STATUS=$(curl -s $API/verify/bulk/$JOB_ID -H "X-API-Key: $MAILVALID_API_KEY" | jq -r .status)
echo "Job $JOB_ID: $STATUS"
case $STATUS in completed|failed|cancelled) break ;; esac
sleep 5
done
curl -s "$API/verify/bulk/$JOB_ID/download?format=csv" \
-H "X-API-Key: $MAILVALID_API_KEY" -o results.csvimport os
import time
import requests
API = "https://mailvalid.io/api/v1"
HEADERS = {"X-API-Key": os.environ["MAILVALID_API_KEY"]}
def verify_list(emails: list[str]) -> str:
job = requests.post(f"{API}/verify/bulk", headers=HEADERS,
json={"emails": emails}, timeout=60)
job.raise_for_status()
job_id = job.json()["job_id"]
while True:
status = requests.get(f"{API}/verify/bulk/{job_id}", headers=HEADERS, timeout=30)
status.raise_for_status()
state = status.json()["status"]
if state in ("completed", "failed", "cancelled"):
break
time.sleep(5)
if state == "failed":
raise RuntimeError(status.json()["error_message"])
csv = requests.get(f"{API}/verify/bulk/{job_id}/download",
headers=HEADERS, params={"format": "csv"}, timeout=60)
csv.raise_for_status()
return csv.text
with open("results.csv", "w", encoding="utf-8", newline="") as f:
f.write(verify_list(["john@company.com", "jane@example.org"]))import { writeFile } from "node:fs/promises";
const API = "https://mailvalid.io/api/v1";
const headers = { "X-API-Key": process.env.MAILVALID_API_KEY, "Content-Type": "application/json" };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(path, init = {}) {
const response = await fetch(API + path, { headers, ...init });
if (!response.ok) throw new Error(`MailValid ${response.status}: ${await response.text()}`);
return response;
}
const { job_id } = await (await call("/verify/bulk", {
method: "POST",
body: JSON.stringify({ emails: ["john@company.com", "jane@example.org"] }),
})).json();
let job;
do {
await sleep(5000);
job = await (await call(`/verify/bulk/${job_id}`)).json();
} while (!["completed", "failed", "cancelled"].includes(job.status));
if (job.status === "failed") throw new Error(job.error_message);
const csv = await (await call(`/verify/bulk/${job_id}/download?format=csv`)).text();
await writeFile("results.csv", csv);<?php
function mailvalid(string $method, string $path, ?array $body = null): string {
$ch = curl_init("https://mailvalid.io/api/v1" . $path);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => [
"X-API-Key: " . getenv("MAILVALID_API_KEY"),
"Content-Type: application/json",
],
]);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 400) {
throw new Exception("MailValid error $status: $response");
}
return $response;
}
$job = json_decode(mailvalid("POST", "/verify/bulk", ["emails" => ["john@company.com", "jane@example.org"]]), true);
do {
sleep(5);
$state = json_decode(mailvalid("GET", "/verify/bulk/{$job['job_id']}"), true);
} while (!in_array($state["status"], ["completed", "failed", "cancelled"]));
file_put_contents("results.csv", mailvalid("GET", "/verify/bulk/{$job['job_id']}/download?format=csv"));Webhooks
Pass a webhook_url when you submit a bulk job and we
POST to it when the job completes, fails or is cancelled, so you
don't need to poll. We wait up to 30 seconds for your server to
answer with a 2xx status. Reply quickly and do any slow
work afterwards. If your server was down, the job's
webhook_delivered field stays false, so you
can poll the job as a fallback.
{
"event": "job.completed",
"timestamp": "2026-10-15T07:21:42.501Z",
"data": {
"job_id": "03fb2d9c-39c7-4ac0-9081-8778faf5c05c",
"status": "completed",
"total_emails": 3,
"processed_emails": 3,
"valid_count": 1,
"invalid_count": 2,
"credits_used": 3,
"started_at": "2026-10-15T07:21:41.912Z",
"completed_at": "2026-10-15T07:21:42.433Z",
"error_message": null,
"results_summary": {
"total": 3,
"results_url": "https://mailvalid.io/api/v1/verify/bulk/03fb2d9c-39c7-4ac0-9081-8778faf5c05c"
}
}
}
results_summary is only included for
job.completed. Fetch the results from
results_url (with your API key) or from the download endpoint.
Headers
| Header | Description |
|---|---|
X-Mailvalid-Signature | HMAC-SHA256 of the raw request body, as hex, signed with your webhook secret |
X-MailValid-Event | job.completed, job.failed or job.cancelled |
Content-Type | application/json |
Verify the signature
Check the signature before trusting a webhook, so nobody else can fake one. Get your secret once with your API key. It is the same secret shown in your dashboard and doesn't change.
curl https://mailvalid.io/api/v1/webhooks/secret \
-H "X-API-Key: $MAILVALID_API_KEY"
# {"webhook_secret": "..."}Compute the HMAC over the exact bytes you received. Don't parse and re-serialise the JSON first, or the signature won't match.
# body.json holds the raw request body exactly as received
EXPECTED=$(openssl dgst -sha256 -hmac "$MAILVALID_WEBHOOK_SECRET" -hex < body.json | sed 's/^.* //')
[ "$EXPECTED" = "$SIGNATURE_HEADER" ] && echo "valid" || echo "reject"import hashlib
import hmac
import os
from flask import Flask, abort, request
app = Flask(__name__)
WEBHOOK_SECRET = os.environ["MAILVALID_WEBHOOK_SECRET"]
@app.post("/webhooks/mailvalid")
def mailvalid_webhook():
raw = request.get_data() # raw bytes, not request.json
expected = hmac.new(WEBHOOK_SECRET.encode(), raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Mailvalid-Signature", "")):
abort(401)
event = request.get_json()
if event["event"] == "job.completed":
job_id = event["data"]["job_id"]
# queue a task that downloads the results for job_id
return "", 200import crypto from "node:crypto";
import express from "express";
const app = express();
const secret = process.env.MAILVALID_WEBHOOK_SECRET;
// express.raw keeps the exact bytes the signature was computed over
app.post("/webhooks/mailvalid", express.raw({ type: "application/json" }), (req, res) => {
const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
const received = req.get("X-Mailvalid-Signature") || "";
if (expected.length !== received.length ||
!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
if (event.event === "job.completed") {
// queue a task that downloads the results for event.data.job_id
}
res.sendStatus(200);
});
app.listen(3000);<?php
$raw = file_get_contents("php://input"); // raw bytes, before json_decode
$expected = hash_hmac("sha256", $raw, getenv("MAILVALID_WEBHOOK_SECRET"));
$received = $_SERVER["HTTP_X_MAILVALID_SIGNATURE"] ?? "";
if (!hash_equals($expected, $received)) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
if ($event["event"] === "job.completed") {
// queue a task that downloads the results for $event["data"]["job_id"]
}
http_response_code(200);Bounce Webhook
Feed delivery and bounce data back to MailValid to improve verification accuracy over time. This is especially valuable for providers that block SMTP verification (Microsoft, Apple) where we can't confirm mailboxes directly.
Improve accuracy automatically
The more bounce data you send, the more accurate future verifications become. Historical data is checked before SMTP verification, so known addresses return results instantly.
/api/v1/webhooks/bounce
API Key Required
Submit Bounce/Delivery Events
Send up to 1,000 bounce or delivery events per request. Hard bounces automatically invalidate cached verification results.
Event Types
| Event Type | Effect | Description |
|---|---|---|
delivered |
Marks valid | Email was successfully delivered to inbox |
hard_bounce |
Marks invalid | Permanent bounce — mailbox doesn't exist (550) |
soft_bounce |
Recorded | Temporary bounce — mailbox full, server down (452) |
complaint |
Marks do_not_mail | Recipient marked email as spam |
unsubscribe |
Recorded | Recipient unsubscribed from emails |
Request Body
{
"events": [
{
"email": "user@example.com",
"event_type": "hard_bounce",
"bounce_code": "550",
"bounce_message": "User unknown",
"timestamp": "2026-03-14T10:30:00Z"
},
{
"email": "valid@example.com",
"event_type": "delivered"
}
]
}
Example
curl -X POST https://mailvalid.io/api/v1/webhooks/bounce \
-H "X-API-Key: mv_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"events": [
{"email": "bounced@example.com", "event_type": "hard_bounce", "bounce_code": "550"},
{"email": "good@example.com", "event_type": "delivered"}
]
}'
Response
{
"success": true,
"processed": 2,
"errors": 0,
"message": "Processed 2/2 events"
}
Job Management
List your bulk jobs, download their results and cancel jobs that are still running. All three are free and use the read limit (cancel uses the verification limit).
List jobs
/api/v1/verify/bulk
| Query parameter | Default | Description |
|---|---|---|
page | 1 | Page number, starting at 1 |
page_size | 20 | Jobs per page, 1 to 100 |
status | all | Only jobs with this status: pending, processing, completed, failed or cancelled |
curl "https://mailvalid.io/api/v1/verify/bulk?page=1&page_size=20&status=completed" \
-H "X-API-Key: $MAILVALID_API_KEY"{
"jobs": [
{
"job_id": "03fb2d9c-39c7-4ac0-9081-8778faf5c05c",
"status": "completed",
"total_emails": 3,
"processed_emails": 3,
"valid_count": 1,
"invalid_count": 2,
"progress_percentage": 100.0,
"credits_used": 3,
"filename": "leads-q3.csv",
"created_at": "2026-10-15T07:21:41.864Z",
"completed_at": "2026-10-15T07:21:42.433Z"
}
],
"total": 41,
"page": 1,
"page_size": 20,
"has_more": true
}Keep requesting the next page while has_more is true.
Download results
/api/v1/verify/bulk/{job_id}/download
| Query parameter | Default | Description |
|---|---|---|
format | json | json (an array of result objects) or csv |
filter | all | Only rows with one status: valid, invalid, catch_all, unknown or do_not_mail |
# Every row as CSV
curl "https://mailvalid.io/api/v1/verify/bulk/{job_id}/download?format=csv" \
-H "X-API-Key: $MAILVALID_API_KEY" -o results.csv
# Only the addresses that are safe to send to
curl "https://mailvalid.io/api/v1/verify/bulk/{job_id}/download?format=csv&filter=valid" \
-H "X-API-Key: $MAILVALID_API_KEY" -o valid.csvemail,status,is_valid,confidence_score,status_reason,syntax_valid,domain,domain_valid,has_mx,provider,is_disposable,is_role_based,is_catch_all,is_free_provider,smtp_response_code,verification_time_ms,cached
john@company.com,valid,True,95,mailbox_confirmed,True,company.com,True,True,google,False,False,False,False,250,598.7,False
Results can be downloaded once a job is completed or
cancelled (you get the rows that finished). Earlier, the
endpoint returns 400 Job not completed. Status: processing.
Get your own columns back
Send source_data with the job and your columns are added
to the right of each row in the download, so the results line up
with your original file. rows is keyed by email in lower
case, with values in the same order as columns. Up to 40
columns. Longer values are cut to 500 characters.
{
"emails": ["john@company.com", "jane@example.org"],
"source_data": {
"columns": ["first_name", "company"],
"rows": {
"john@company.com": ["John", "Company Inc"],
"jane@example.org": ["Jane", "Example Org"]
}
}
}Cancel a job
/api/v1/verify/bulk/{job_id}
Stops a pending or processing job. Addresses
already checked are charged and kept. Credits reserved for the rest
are released.
curl -X DELETE https://mailvalid.io/api/v1/verify/bulk/{job_id} \
-H "X-API-Key: $MAILVALID_API_KEY"{
"success": true,
"message": "Job cancelled successfully",
"job_id": "03fb2d9c-39c7-4ac0-9081-8778faf5c05c"
}
A job that already finished returns
400 Cannot cancel job with status: completed.
Credits
Your current balance and how many credits you have used in total.
Free to call. Check it before a large bulk job, because a job is
refused with 402 when you don't have enough credits to
reserve.
/api/v1/credits
curl https://mailvalid.io/api/v1/credits \
-H "X-API-Key: $MAILVALID_API_KEY"{
"balance": 69372,
"lifetime_used": 1631
}Credits never expire. Buy more from Dashboard → Billing.
MCP Server (Model Context Protocol)
Connect AI agents and assistants — Claude, Cursor, and any MCP-compatible client — directly to MailValid. The MCP server is a hosted remote endpoint over the Streamable HTTP transport. Its tools run through the same verification engine and credit system as the REST API, so billing is identical.
| Endpoint | https://mailvalid.io/mcp |
| Transport | Streamable HTTP (use the http transport in your client) |
| Authentication | Your API key in the X-API-Key header (or Authorization: Bearer mv_live_...) |
| Billing | Identical to the REST API — single verification costs 1 credit, bulk reserves credits, reads are free |
Every tool requires the X-API-Key header and bills your
account. Follow the instructions for your client below.
Claude Code
Run this command in your terminal:
claude mcp add --transport http mailvalid https://mailvalid.io/mcp \
--header "X-API-Key: mv_live_your_key_here"
Then run /mcp in Claude Code to confirm the connection
and manage installed servers, and /context to see token
usage per server.
Cursor
- Open Cursor Settings → MCP → Add new global MCP server
- Paste the configuration below, then save and restart Cursor
{
"mcpServers": {
"mailvalid": {
"url": "https://mailvalid.io/mcp",
"headers": { "X-API-Key": "mv_live_your_key_here" }
}
}
}
The verify_email tool and others are available
immediately — no separate OAuth step, since auth is your API key.
VS Code (GitHub Copilot)
- Create a
.vscode/mcp.jsonfile in your workspace with the config below - Open the Command Palette (
Cmd+Shift+P/Ctrl+Shift+P) and run MCP: List Servers - Start the MailValid server — tools are available immediately
{
"servers": {
"mailvalid": {
"type": "http",
"url": "https://mailvalid.io/mcp",
"headers": { "X-API-Key": "mv_live_your_key_here" }
}
}
}
Claude Desktop
Claude Desktop's config file only runs local (stdio) MCP servers, so use the
@mailvalid/mcp launcher instead of connecting directly
over HTTP. It needs Node.js 18 or newer:
- Open Settings → Developer → Edit Config
- Add the MailValid server below to your config
- Fully quit Claude Desktop (from the menu bar or system tray, not just the window) and reopen it
{
"mcpServers": {
"mailvalid": {
"command": "npx",
"args": ["-y", "@mailvalid/mcp"],
"env": { "MAILVALID_API_KEY": "mv_live_your_key_here" }
}
}
}
The launcher reads your key from MAILVALID_API_KEY and
bridges to the hosted server — there's no URL or header to manage by
hand.
Windsurf
- Open Windsurf Settings (
Cmd+,on Mac) and search for MCP - Select View raw config to open
mcp_config.json - Add the MailValid server below, then save and restart Windsurf
{
"mcpServers": {
"mailvalid": {
"serverUrl": "https://mailvalid.io/mcp",
"headers": { "X-API-Key": "mv_live_your_key_here" }
}
}
}
Other MCP clients
If your client isn't listed above, use one of these transports:
| Transport | URL | Notes |
|---|---|---|
| Streamable HTTP (recommended) | https://mailvalid.io/mcp |
/mcp/ with a trailing slash also works |
@mailvalid/mcp launcher |
via npx -y @mailvalid/mcp |
For stdio-only clients (Claude Desktop and similar) |
{
"mcpServers": {
"mailvalid": {
"url": "https://mailvalid.io/mcp",
"headers": { "X-API-Key": "mv_live_your_key_here" }
}
}
}
{
"mcpServers": {
"mailvalid": {
"command": "npx",
"args": ["-y", "@mailvalid/mcp"],
"env": { "MAILVALID_API_KEY": "mv_live_your_key_here" }
}
}
}
Field names vary slightly between clients (some use
servers instead of mcpServers) — check
your client's MCP documentation for the expected key names.
Available tools
All tools require your API key:
| Tool | Auth | Cost | Description |
|---|---|---|---|
verify_email |
API key | 1 credit* | Verify one address — syntax, DNS/MX, SMTP mailbox, disposable/role/catch-all, confidence. Args: email. |
submit_bulk_verification |
API key | Reserves N | Queue a list for asynchronous verification. Args: emails (array), optional webhook_url. |
get_bulk_job |
API key | Free | Status, progress, and (when complete) results of a bulk job. Args: job_id. |
list_bulk_jobs |
API key | Free | List your recent bulk jobs (paginated). Args: page, page_size, status. |
cancel_bulk_job |
API key | Free | Cancel a pending/processing job and release reserved credits. Args: job_id. |
get_credit_balance |
API key | Free | Your current credit balance and lifetime usage. |
* verify_email is free for unknown results
— the same fair-billing rule as the REST API.
Troubleshooting
My MCP client doesn't support remote HTTP servers
Use the @mailvalid/mcp launcher instead — it works over stdio in any client, including Claude Desktop. See the config under Other MCP clients.
I'm getting connection errors
Make sure your endpoint URL is exactly https://mailvalid.io/mcp and your API key is sent in the X-API-Key header.
401 / authentication errors
Confirm your API key is passed as X-API-Key (or Authorization: Bearer mv_live_...) and that it hasn't been revoked in your dashboard. Call get_credit_balance first: it's free, so it confirms the connection and the key without spending credits.
"npx is not recognized" or "spawn npx ENOENT"
Node.js isn't installed or isn't on your PATH. Install it from nodejs.org and restart your MCP client. On Windows you can also use "command": "cmd" with "args": ["/c", "npx", "-y", "@mailvalid/mcp"].
MailValid doesn't show up in Claude Desktop
Check that the config is valid JSON (one missing comma stops the whole file from loading), then fully quit Claude Desktop and reopen it. Settings → Developer shows whether the server started.
My MCP client isn't listed here
Use the generic Streamable HTTP configuration under Other MCP clients. If your client needs a different config shape (some use servers instead of mcpServers), check that client's own MCP documentation for the expected key names.
FAQ
Does billing work the same as the REST API?
Yes — the MCP tools call the same verification engine and draw from the same credit balance as the REST API and web dashboard. A verify_email call costs exactly what a POST /api/v1/verify/single call costs.
What's the difference between the launcher and connecting directly?
The @mailvalid/mcp launcher runs locally over stdio and is the only option for clients that don't support remote HTTP servers (like Claude Desktop). If your client supports Streamable HTTP directly (Claude Code, Cursor, VS Code), connecting straight to https://mailvalid.io/mcp skips the extra process and is the simpler setup.
Is there a discovery endpoint for agents that want to find this automatically?
Yes — /.well-known/mcp.json and /.well-known/mcp/server-card.json.
See the REST endpoints above for the underlying API these tools call, or the full agent integration guide for a self-contained reference covering both REST and MCP.
HTTP Response Codes
| Code | Meaning | When it happens |
|---|---|---|
| 200 | OK | Success. Bulk jobs are also created with 200. |
| 400 | Bad Request | The action isn't possible right now, for example downloading a job that is still running or cancelling a finished one |
| 401 | Unauthorized | The API key is missing, wrong or revoked |
| 402 | Payment Required | Not enough credits for the request |
| 404 | Not Found | The job doesn't exist or belongs to another account |
| 413 | Content Too Large | The bulk list is bigger than your plan allows (100 on Free, 10,000 on paid plans) |
| 422 | Unprocessable Entity | The request body or a parameter is invalid, for example a badly formed email on /verify/single |
| 429 | Too Many Requests | Rate limit reached. Wait for Retry-After seconds. |
| 5xx | Server error | Something went wrong on our side. Retry with backoff. |
Email Status Values
status is the verdict to act on. status_reason
says why, as a code you can switch on in your own logic.
| status | is_valid | Meaning | Credits | Action |
|---|---|---|---|---|
| valid | true | The mail server confirmed the mailbox exists | 1 | Send |
| invalid | false | Bad syntax, no such domain, no mail server, or the mailbox doesn't exist | 1 | Don't send |
| catch_all | false | The domain accepts every address, so this mailbox can't be confirmed | 1 | Send with care |
| do_not_mail | false | May work but is risky: disposable, role-based, or a past spam complaint | 1 | Don't send marketing |
| unknown | false | No clear answer: the provider blocks checks, timed out or asked us to retry | 0 | Retry later |
Reasons (status_reason)
| status_reason | status | Meaning |
|---|---|---|
mailbox_confirmed | valid | The mail server accepted the address (SMTP 250) |
historical_delivery_confirmed | valid | Mail to this address was delivered before (from bounce webhook data) |
mailbox_not_found | invalid | The mail server rejected the address (SMTP 550) |
email_format_invalid | invalid | The address is badly formed (bulk jobs) |
failed_syntax_check | invalid | The address is badly formed |
domain_does_not_exist | invalid | The domain doesn't exist |
no_dns_entries | invalid | The domain has no DNS records |
no_mx_records | invalid | The domain exists but has no mail servers |
historical_hard_bounce | invalid | Mail to this address hard-bounced before |
accept_all | catch_all | The domain accepts any address |
disposable | do_not_mail | Temporary inbox provider, such as mailinator.com |
role_based | do_not_mail | Team address such as info@, support@ or admin@ |
historical_complaint | do_not_mail | The recipient marked mail as spam before |
failed_smtp_connection | unknown | The provider blocks mailbox checks (common for Microsoft and Apple) |
antispam_system | unknown | An anti-spam system blocked the check |
greylisted | unknown | The server asked us to try again later |
mail_server_temporary_error | unknown | The mail server returned a temporary error |
historical_soft_bounce | unknown | Mail to this address soft-bounced before |
verification_timeout | unknown | The mail server was too slow to answer |
verification_error | unknown | The check failed for an unexpected reason |
Confidence score
confidence_score (0 to 100) says how sure the verdict is.
| Range | Typical cause |
|---|---|
| 90 to 100 | Confirmed by the mail server, a past hard bounce, or a syntax or domain failure |
| 70 to 89 | Past delivery data or a trusted provider response |
| 40 to 69 | Catch-all domain, greylisting or a past soft bounce |
| 0 to 39 | The provider blocked the check, or it timed out |
Rate Limits
Limits are per API key and per minute, in two separate buckets. The
verification bucket covers requests that do work
(POST and DELETE). The read
bucket covers GET requests such as polling a job or
checking credits, so polling never slows down your verifications.
| Plan | Verification requests | Read requests | Emails per bulk job |
|---|---|---|---|
| Free | 10 / min | 60 / min | 100 |
| Paid (MailValid Plus or pay-as-you-go) | 200 / min | 800 / min | 10,000 |
For more than 200 checks a minute, use a bulk job: one request checks up to 10,000 addresses. Need higher limits? Email sachin@mailvalid.io.
Rate limit headers
| Header | Description |
|---|---|
X-RateLimit-Limit | Requests allowed per minute in this bucket |
X-RateLimit-Remaining | Requests left in the current minute |
X-RateLimit-Bucket | compute (verification) or read |
Retry-After | Only on a 429: seconds to wait before retrying |
{
"detail": "Rate limit exceeded. Try again in 12s."
}Retry on 429 and server errors
# --retry retries 429 (honouring Retry-After) and 5xx errors, not 401 or 402
curl --retry 5 -X POST https://mailvalid.io/api/v1/verify/single \
-H "X-API-Key: $MAILVALID_API_KEY" -H "Content-Type: application/json" \
-d '{"email": "john@company.com"}'import time
import requests
def post_with_retry(url: str, max_attempts: int = 5, **kwargs) -> requests.Response:
for attempt in range(max_attempts):
response = requests.post(url, timeout=30, **kwargs)
if response.status_code == 429:
time.sleep(int(response.headers.get("Retry-After", "5")))
elif response.status_code >= 500:
time.sleep(2 ** attempt)
else:
return response
response.raise_for_status()
return responseconst sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function postWithRetry(url, init, maxAttempts = 5) {
let response;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
response = await fetch(url, { method: "POST", ...init });
if (response.status === 429) {
await sleep(Number(response.headers.get("Retry-After") ?? 5) * 1000);
} else if (response.status >= 500) {
await sleep(2 ** attempt * 1000);
} else {
return response;
}
}
return response;
}<?php
function post_with_retry(string $url, array $headers, string $body, int $maxAttempts = 5): array {
for ($attempt = 0; $attempt < $maxAttempts; $attempt++) {
$retryAfter = 5;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_TIMEOUT => 30,
CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$retryAfter) {
if (stripos($line, "Retry-After:") === 0) {
$retryAfter = (int) trim(substr($line, 12));
}
return strlen($line);
},
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status === 429) {
sleep($retryAfter);
} elseif ($status >= 500) {
sleep(2 ** $attempt);
} else {
return [$status, json_decode($response, true)];
}
}
throw new Exception("MailValid request failed after $maxAttempts attempts");
}
Don't retry 400, 401, 402,
404, 413 or 422. They fail the
same way every time until you change the request.
Errors
Every error returns a JSON body with a detail field.
Usually it is a message you can show or log:
{
"detail": "Insufficient credits. Required: 500, Available: 120"
}
For a 422, detail is a list with one entry
per problem. loc points at the field:
{
"detail": [
{
"type": "value_error",
"loc": ["body", "email"],
"msg": "value is not a valid email address: An email address must have an @-sign.",
"input": "not-an-email"
}
]
}Common errors
| Status | detail | Fix |
|---|---|---|
| 401 | API key required. Include X-API-Key header. | Add the X-API-Key header |
| 401 | Invalid API key | Check the key, or create a new one |
| 402 | Insufficient credits. Required: N, Available: M | Buy credits, or send a smaller list |
| 404 | Bulk job not found | Check the job ID and that it was created with this account's key |
| 400 | Job not completed. Status: processing | Wait until the job completes, then download |
| 400 | Cannot cancel job with status: completed | Only pending or processing jobs can be cancelled |
| 413 | Bulk job too large for the free plan: … | Split the list, or upgrade for 10,000 per job |
| 422 | A list of field errors | Fix the field named in loc |
| 429 | Rate limit exceeded. Try again in Ns. | Wait for Retry-After seconds |
Handling errors
# -w prints the status code after the body; --fail-with-body exits non-zero on 4xx/5xx
curl --fail-with-body -w "\n%{http_code}\n" -X POST https://mailvalid.io/api/v1/verify/single \
-H "X-API-Key: $MAILVALID_API_KEY" -H "Content-Type: application/json" \
-d '{"email": "john@company.com"}'response = requests.post(url, headers=headers, json={"email": email}, timeout=30)
if response.status_code == 200:
result = response.json()["result"]
elif response.status_code == 402:
notify_team("MailValid is out of credits")
elif response.status_code == 422:
for problem in response.json()["detail"]:
print(problem["loc"][-1], problem["msg"])
else:
raise RuntimeError(f"MailValid {response.status_code}: {response.json().get('detail')}")const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({ email }) });
const body = await response.json();
if (response.ok) {
console.log(body.result.status);
} else if (response.status === 422) {
for (const problem of body.detail) console.log(problem.loc.at(-1), problem.msg);
} else {
throw new Error(`MailValid ${response.status}: ${body.detail}`);
}<?php
[$status, $body] = post_with_retry($url, $headers, json_encode(["email" => $email]));
if ($status === 200) {
echo $body["result"]["status"];
} elseif ($status === 422) {
foreach ($body["detail"] as $problem) {
echo end($problem["loc"]) . ": " . $problem["msg"] . "\n";
}
} else {
throw new Exception("MailValid $status: " . json_encode($body["detail"]));
}Need Help?
Can't find what you're looking for? Get in touch with our support team.
Ready to verify emails in your app?
Create a free account to get your API key. Pay only for definitive results.
Get your free API key