Sign inStart my free trial
mailfloss · API

Email verification, as a single endpoint.

A REST API for verifying email addresses — JSON in, JSON out. Built for product teams and AI agents that need programmatic answers, not dashboards.

10,000 / min
default rate limit — raise on request
99.996%
uptime — Live status →
20+
verification checks per address
Bearer · JSON
auth · format · OpenAPI 3.1 spec
GET · api.mailfloss.com
Request
curl "https://api.mailfloss.com/v1/[email protected]" \
  -H "Authorization: Bearer $MAILFLOSS_API_KEY"
200 OKResponse · application/json
{
  "email": "[email protected]",
  "domain": "theshire.com",
  "status": "passed",
  "reason": "valid",
  "passed": true,
  "role": false,
  "disposable": false,
  "free": false,
  "suggestion": "",
  "meta": ""
}
In short

What does the mailfloss email verification API do?

The mailfloss email verification API checks whether an email address is valid, deliverable, disposable, role-based, or likely to bounce — in real time, from your own code. Send an address to a single REST endpoint and get back a clear result plus the risk signals you can act on at signup, checkout, or form submission. It's the same verification engine behind mailfloss's automated list cleaning, exposed for developers.

The verify endpoint

GET one address. Get back a verdict.

A single GET with your key in a Bearer header and the address as a query param. No SDK required — plain HTTPS works in any language.

GET /v1/verify
curl "https://api.mailfloss.com/v1/[email protected]" \
  -H "Authorization: Bearer $MAILFLOSS_API_KEY"
200 OKResponse
application/json
{
  "email": "[email protected]",
  "domain": "theshire.com",
  "status": "passed",
  "reason": "valid",
  "passed": true,
  "role": false,
  "disposable": false,
  "free": false,
  "suggestion": "",
  "meta": ""
}
X-Request-Id: req_…returned as a response header · 1 credit / verification
status is a closed enum
passedundeliverableriskyunknown

Spotted a typo? When an address looks misspelled, mailfloss returns the likely correction in the suggestion field — here gmial.cmo becomes gmail.com. status stays the deliverability verdict; the fix always lives in suggestion, so you can offer the user a “Did you mean…?” prompt.

{
  "email": "[email protected]",
  "domain": "gmial.cmo",
  "status": "undeliverable",
  "reason": "invalid",
  "passed": false,
  "suggestion": "[email protected]",
  "meta": ""
}
Endpoints

The developer surface.

Made for the AI era — every endpoint returns deterministic JSON an agent can call directly, no scraping or screen-reading required. Bearer token only. Rate limit is 10,000 requests/min per key — a 429 includes a Retry-After header. POST routes accept an Idempotency-Key header for safe retries.

Verify
GET/v1/verifyVerify a single email address.
Batch
POST/v1/batch-verifySubmit a list of addresses for async verification.
GET/v1/batch-verify/{id}/statusCheck progress of a batch job.
GET/v1/batch-verify/{id}/resultsRetrieve results once the job is finished.
POST/v1/batch-verify/{id}/cancelCancel a running batch job.
Jobs
GET/v1/jobsList your verification jobs.
GET/v1/jobs/{id}Fetch a single job.
Usage
GET/v1/reports/usageRemaining credits and usage for the current period.
Account
GET/v1/check-keyValidate an API key.
GET/v1/accountAccount details and credit balance.
GET/v1/organizationOrganization details.
Privacy
POST/v1/erasuresSubmit a data-erasure (GDPR / CCPA) request.
Webhooks

Get pushed the result — skip the polling.

Two flavors: a per-job webhook on batch verifications, and broader account webhooks that fire as your lists are cleaned.

API-level · batch webhook

Pass a webhook_url to a batch job and mailfloss POSTs the finished job — its id and verdict summary — to that URL, so you never have to poll for status.

POST /v1/batch-verify

{
  "emails": ["[email protected]", "[email protected]"],
  "webhook_url": "https://you.com/hook"
}

Account webhooks

React to changes across your mailfloss account — these fire as your lists are cleaned, not on individual /v1/verify calls. Each webhook is a name, one or more trigger events, a destination URL, a data source, and an optional secret.

Configured today in the dashboard → API & Webhooks
Programmatic /v1/webhooks management — coming soon
25+ granular triggers, in dot notation
status.*
status.undeliverablestatus.riskystatus.unknown
reason.*
reason.bouncedreason.invalidreason.rolereason.disposablereason.blacklistedreason.accept_allreason.spamreason.complainer…
contact.*
contact.fixedcontact.unsubscribedcontact.deletedcontact.taggedcontact.updated
job
job.finished
Payload mailfloss POSTs

Flat JSON body. email, domain, status, reason, passed, processed and integration are always present; suggestion appears on fixes; an event-specific boolean (fixed / unsubscribed / deleted / tagged / updated) accompanies contact.* events; event is the dot-notation trigger.

{
  "email": "[email protected]",
  "domain": "gmial.cmo",
  "status": "risky",
  "reason": "accept_all",
  "passed": false,
  "processed": true,
  "integration": "mailchimp",
  "suggestion": "[email protected]",
  "fixed": true,
  "event": "contact.fixed"
}

Verify the signature

When a webhook secret is set, every delivery carries an X-Request-Signature header — an HMAC-SHA1 of the raw JSON body, keyed by your secret.

const sig = crypto
  .createHmac('sha1', SECRET)
  .update(rawBody)
  .digest('hex');
 
// constant-time compare
sig === req.headers['x-request-signature'];

Delivery

Respond 200 to acknowledge a delivery.
Non-200 responses are retried with exponential backoff — 5 retries over ~60s to 5 min.
After 5 straight failures the webhook is auto-deactivated.
Best-effort: no ordering guarantee, and events may arrive in bursts.
Built for

Use cases that match the surface area.

PRODUCT TEAMS

Verify signups inline

Pass every incoming address through verify before it hits your users table — block disposable, surface a typo suggestion, reject invalid, all in one request.

GET /v1/verify
AI AGENTS

Resolve addresses programmatically

Agents need ground-truth on whether an address is real. mailfloss returns a deterministic verdict with a closed status enum and structured reasons — ideal for tool calls.

GET /v1/verify · structured JSON · idempotent reads
BULK VERIFICATION

Clean an inherited list

Acquired a database, or got a CSV from a partner? Submit the whole list to batch-verify and pass a webhook_url to get notified upon completion.

POST /v1/batch-verify
TRANSACTIONAL EMAIL

Verify before you send

Check an address right before a password reset, receipt, or magic link goes out — so critical mail doesn’t bounce and your sender reputation stays clean.

GET /v1/verify
Clients

No SDK required — plain HTTPS works.

Every endpoint is a plain HTTPS call with a Bearer header, so any language with an HTTP client is ready today. Typed SDKs are on the way.

Typed SDKs — coming soon
NodeSoon
PythonSoon
GoSoon
RubySoon
API pricing

Pay per verification. No subscription required.

Prepaid credits — one credit per verification. The bigger the pack, the lower the per-credit price.

Credits
One-time price
Per credit
1,000
$8
$0.008
10,000
$40
$0.004
50,000
$160
$0.0032
100,000
$300
$0.003
250,000
$500
$0.002
500,000
$800
$0.0016
1,000,000
$1,200
$0.0012
2,500,000
$2,600
$0.00104
Prices shown + tax. A standing 15% promo currently applies at checkout. Need higher volume? See the full pricing page.
See full pricing
API FAQ

Common questions.

10,000 requests per minute per API key by default. Exceed it and you get a 429 with a Retry-After header telling you when to retry. Need more? Email us with your expected throughput and we’ll raise it.
Ready when you are

Stop paying to email a leaky list.

Connect your email platform in 30 seconds. mailfloss starts catching typos and cleaning your list on autopilot.

Free 7-day trialEasy setupMoney-back guarantee