Black Friday Sale

Use code: BLACKFRIDAY50

50% OFF on all prices
Ends in: 00d: 00h: 00m: 00s

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.

Open raw file

Fast & Reliable

Average response time under 500ms

99% Accuracy

Provider-optimized verification

Bulk Support

Up to 10,000 emails per job

Base URL
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
curl https://mailvalid.io/api/v1/credits \
  -H "X-API-Key: mv_live_your_key_here"
Response · 200 OK
{
  "balance": 100,
  "lifetime_used": 0
}

Authentication errors

StatusdetailWhat to do
401API key required. Include X-API-Key header.Send the key in the X-API-Key header.
401Invalid API keyThe key is wrong, deleted or revoked. Copy it again or create a new one.
401Invalid or expired tokenYou 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:

Terminal
export MAILVALID_API_KEY="mv_live_your_key_here"
cURL
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"}'
Python (requests)
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_confirmed
JavaScript (Node.js 18+)
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: "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 (cURL)
<?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_mail

What to do with the result

statusMeaningSuggested action
validThe mailbox existsSend
invalidThe address will bounceRemove it, or ask the user to fix a typo
catch_allThe domain accepts every address, so the mailbox can't be confirmedSend with care
do_not_mailDisposable, role-based (info@) or a past spam complaintDon't send marketing email
unknownThe 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.

POST /api/v1/verify/single

Request body

FieldTypeRequiredDescription
emailstringRequiredThe address to check. A badly formed address is rejected with 422 and costs nothing.
cURL
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"}'
Python (requests)
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"])
JavaScript (Node.js 18+)
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 (cURL)
<?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"];
Response · 200 OK
{
  "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

FieldTypeDescription
successbooleanAlways true on a 200 response
credits_usedintegerThe final charge for this call: 1, or 0 for unknown
result.emailstringThe address that was checked
result.statusstringvalid, invalid, catch_all, unknown or do_not_mail
result.is_validbooleantrue only when status is valid
result.status_reasonstringWhy, as a code you can switch on (see Status Values)
result.confidence_scoreinteger0 to 100. How sure the result is
result.syntax_validbooleanThe address is well formed
result.domainstringThe part after the @
result.domain_validbooleanThe domain exists in DNS
result.has_mxbooleanThe domain has mail servers (MX records)
result.mx_recordsarrayThe domain's mail servers, each with priority and host
result.smtp_checkedbooleanThe mailbox was checked over SMTP
result.smtp_response_codeinteger or nullThe mail server's reply code, for example 250 (accepted) or 550 (no such user)
result.is_disposablebooleanTemporary inbox provider, such as mailinator.com
result.is_role_basedbooleanA team address such as info@, support@ or admin@
result.is_catch_allbooleanThe domain accepts mail for any address
result.is_free_providerbooleanA free mailbox provider such as gmail.com or yahoo.com
result.providerstring or nullDetected mailbox provider, for example google, microsoft, yahoo or corporate
result.verification_time_msnumber or nullHow long the check took
result.cachedbooleanThe 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 returns 422. 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 invalid with reason email_format_invalid.
  • Credits for every address are reserved when you submit. Unused credits (for unknown results or a cancelled job) are released when it ends.

1. Submit a job

POST /api/v1/verify/bulk
FieldTypeRequiredDescription
emailsarray of stringsRequiredThe addresses to check, 1 to 10,000
webhook_urlstringOptionalA URL on your server (use https) that we POST to when the job finishes. See Webhooks.
filenamestringOptionalA label such as leads-q3.csv, shown on the job so you can recognise it. Up to 255 characters.
source_dataobjectOptionalYour own extra columns (name, company…), added back to the right of each row in the download. See Download results.
cURL
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"
  }'
Response · 200 OK
{
  "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

GET /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).

Response · 200 OK
{
  "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

Bash (cURL + jq)
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.csv
Python (requests)
import 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"]))
JavaScript (Node.js 18+)
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 (cURL)
<?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.

Webhook payload
{
  "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

HeaderDescription
X-Mailvalid-SignatureHMAC-SHA256 of the raw request body, as hex, signed with your webhook secret
X-MailValid-Eventjob.completed, job.failed or job.cancelled
Content-Typeapplication/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
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.

Bash (openssl)
# 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"
Python (Flask)
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 "", 200
JavaScript (Express)
import 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
<?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.

POST /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

JSON
{
  "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
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

JSON
{
  "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

GET /api/v1/verify/bulk
Query parameterDefaultDescription
page1Page number, starting at 1
page_size20Jobs per page, 1 to 100
statusallOnly jobs with this status: pending, processing, completed, failed or cancelled
cURL
curl "https://mailvalid.io/api/v1/verify/bulk?page=1&page_size=20&status=completed" \
  -H "X-API-Key: $MAILVALID_API_KEY"
Response · 200 OK
{
  "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

GET /api/v1/verify/bulk/{job_id}/download
Query parameterDefaultDescription
formatjsonjson (an array of result objects) or csv
filterallOnly rows with one status: valid, invalid, catch_all, unknown or do_not_mail
cURL
# 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.csv
CSV columns
email,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.

Request body with source_data
{
  "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

DELETE /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
curl -X DELETE https://mailvalid.io/api/v1/verify/bulk/{job_id} \
  -H "X-API-Key: $MAILVALID_API_KEY"
Response · 200 OK
{
  "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.

GET /api/v1/credits
cURL
curl https://mailvalid.io/api/v1/credits \
  -H "X-API-Key: $MAILVALID_API_KEY"
Response · 200 OK
{
  "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:

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

  1. Open Cursor Settings → MCP → Add new global MCP server
  2. Paste the configuration below, then save and restart Cursor
JSON
{
  "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)

  1. Create a .vscode/mcp.json file in your workspace with the config below
  2. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run MCP: List Servers
  3. Start the MailValid server — tools are available immediately
.vscode/mcp.json
{
  "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:

  1. Open Settings → Developer → Edit Config
  2. Add the MailValid server below to your config
  3. Fully quit Claude Desktop (from the menu bar or system tray, not just the window) and reopen it
JSON
{
  "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

  1. Open Windsurf Settings (Cmd+, on Mac) and search for MCP
  2. Select View raw config to open mcp_config.json
  3. Add the MailValid server below, then save and restart Windsurf
mcp_config.json
{
  "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)
Streamable HTTP (direct connection)
{
  "mcpServers": {
    "mailvalid": {
      "url": "https://mailvalid.io/mcp",
      "headers": { "X-API-Key": "mv_live_your_key_here" }
    }
  }
}
stdio (via the launcher)
{
  "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

CodeMeaningWhen it happens
200OKSuccess. Bulk jobs are also created with 200.
400Bad RequestThe action isn't possible right now, for example downloading a job that is still running or cancelling a finished one
401UnauthorizedThe API key is missing, wrong or revoked
402Payment RequiredNot enough credits for the request
404Not FoundThe job doesn't exist or belongs to another account
413Content Too LargeThe bulk list is bigger than your plan allows (100 on Free, 10,000 on paid plans)
422Unprocessable EntityThe request body or a parameter is invalid, for example a badly formed email on /verify/single
429Too Many RequestsRate limit reached. Wait for Retry-After seconds.
5xxServer errorSomething 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.

statusis_validMeaningCreditsAction
validtrueThe mail server confirmed the mailbox exists1Send
invalidfalseBad syntax, no such domain, no mail server, or the mailbox doesn't exist1Don't send
catch_allfalseThe domain accepts every address, so this mailbox can't be confirmed1Send with care
do_not_mailfalseMay work but is risky: disposable, role-based, or a past spam complaint1Don't send marketing
unknownfalseNo clear answer: the provider blocks checks, timed out or asked us to retry0Retry later

Reasons (status_reason)

status_reasonstatusMeaning
mailbox_confirmedvalidThe mail server accepted the address (SMTP 250)
historical_delivery_confirmedvalidMail to this address was delivered before (from bounce webhook data)
mailbox_not_foundinvalidThe mail server rejected the address (SMTP 550)
email_format_invalidinvalidThe address is badly formed (bulk jobs)
failed_syntax_checkinvalidThe address is badly formed
domain_does_not_existinvalidThe domain doesn't exist
no_dns_entriesinvalidThe domain has no DNS records
no_mx_recordsinvalidThe domain exists but has no mail servers
historical_hard_bounceinvalidMail to this address hard-bounced before
accept_allcatch_allThe domain accepts any address
disposabledo_not_mailTemporary inbox provider, such as mailinator.com
role_baseddo_not_mailTeam address such as info@, support@ or admin@
historical_complaintdo_not_mailThe recipient marked mail as spam before
failed_smtp_connectionunknownThe provider blocks mailbox checks (common for Microsoft and Apple)
antispam_systemunknownAn anti-spam system blocked the check
greylistedunknownThe server asked us to try again later
mail_server_temporary_errorunknownThe mail server returned a temporary error
historical_soft_bounceunknownMail to this address soft-bounced before
verification_timeoutunknownThe mail server was too slow to answer
verification_errorunknownThe check failed for an unexpected reason

Confidence score

confidence_score (0 to 100) says how sure the verdict is.

RangeTypical cause
90 to 100Confirmed by the mail server, a past hard bounce, or a syntax or domain failure
70 to 89Past delivery data or a trusted provider response
40 to 69Catch-all domain, greylisting or a past soft bounce
0 to 39The 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.

PlanVerification requestsRead requestsEmails per bulk job
Free10 / min60 / min100
Paid (MailValid Plus or pay-as-you-go)200 / min800 / min10,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

HeaderDescription
X-RateLimit-LimitRequests allowed per minute in this bucket
X-RateLimit-RemainingRequests left in the current minute
X-RateLimit-Bucketcompute (verification) or read
Retry-AfterOnly on a 429: seconds to wait before retrying
Response · 429 Too Many Requests
{
  "detail": "Rate limit exceeded. Try again in 12s."
}

Retry on 429 and server errors

cURL
# --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"}'
Python (requests)
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 response
JavaScript (Node.js 18+)
const 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 (cURL)
<?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:

Response · 402 Payment Required
{
  "detail": "Insufficient credits. Required: 500, Available: 120"
}

For a 422, detail is a list with one entry per problem. loc points at the field:

Response · 422 Unprocessable Entity
{
  "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

StatusdetailFix
401API key required. Include X-API-Key header.Add the X-API-Key header
401Invalid API keyCheck the key, or create a new one
402Insufficient credits. Required: N, Available: MBuy credits, or send a smaller list
404Bulk job not foundCheck the job ID and that it was created with this account's key
400Job not completed. Status: processingWait until the job completes, then download
400Cannot cancel job with status: completedOnly pending or processing jobs can be cancelled
413Bulk job too large for the free plan: …Split the list, or upgrade for 10,000 per job
422A list of field errorsFix the field named in loc
429Rate limit exceeded. Try again in Ns.Wait for Retry-After seconds

Handling errors

cURL
# -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"}'
Python (requests)
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')}")
JavaScript (Node.js 18+)
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
<?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