MailFloo › Email verification API

Email verification API

Four endpoints, JSON in and out. Verify one address, verify a list with a callback, read results, and send back what really happened.

Updated 18 October 2026·6 min read

Authentication

Every call carries your key in the X-Api-Key header (a Authorization: Bearer header also works). Keys are created on the API page inside MailFloo, can be viewed and copied again later, and are revoked in one click. Each key is limited to 60 requests a minute; the X-RateLimit-Remaining header on every reply tells you where you stand, and a 429 comes with Retry-After.

All replies are JSON. Errors have the shape {"ok": false, "error": "code", "message": "…"}.

Verify one address

POST /api/v1/verify.php checks a single address. If it was verified in the last 30 days the answer is immediate and costs nothing; otherwise pass wait=1 and the call blocks until the three checks finish (up to about 25 seconds), or omit it to get a job id to poll.

curl -X POST https://mailfloo.com/api/v1/verify.php \
  -H "X-Api-Key: mf_live_YOUR_KEY" \
  -d "email=john.smith@acme.com" -d "wait=1"
{
  "ok": true,
  "cached": false,
  "result": {
    "email": "john.smith@acme.com",
    "status": "valid",
    "score": 92,
    "confidence": "very_high",
    "catch_all": false,
    "role": false,
    "free_provider": false,
    "disposable": false,
    "reason": "Mailbox confirmed by its server."
  }
}

Add fresh=1 to bypass the 30-day cache and force a new check.

Verify a list

POST /api/v1/bulk.php takes up to 5,000 addresses per call, as a comma- or newline-separated emails field or a JSON array. Duplicates are counted once. The reply is a job id.

curl -X POST https://mailfloo.com/api/v1/bulk.php \
  -H "X-Api-Key: mf_live_YOUR_KEY" \
  -d "emails=a@acme.com,b@northwind.io,c@contoso.com" \
  -d "name=October leads" \
  -d "callback_url=https://your.app/mailfloo-done"
{ "ok": true, "job_id": 1042, "total": 3, "credited": 3, "status": "queued", "poll": "api/v1/job.php?id=1042" }

If you pass a callback_url, MailFloo POSTs a JSON summary to it when the job finishes (event, job id, final status, counts per result and the URL to fetch results), so you never have to poll:

{ "event": "job.completed", "job_id": 1042, "status": "completed",
  "counts": { "total": 3, "valid": 2, "catch_all": 0, "invalid": 1, "unknown": 0, "duplicate": 0 },
  "results_url": "https://mailfloo.com/api/v1/job.php?id=1042&results=1" }

Get a job's results

GET /api/v1/job.php?id=1042 returns the job's status (queued, processing, completed, cancelled) and counts. Add results=1 for every address, 1,000 per page (&page=2), and status=valid (or catch_all, invalid, unknown) to filter.

curl "https://mailfloo.com/api/v1/job.php?id=1042&results=1&status=valid" \
  -H "X-Api-Key: mf_live_YOUR_KEY"

Teach the engine what really happened

POST /api/v1/outcomes.php is the feedback half of the loop. Send what your mailer saw (delivered or bounced) and MailFloo applies it on the next check: a delivered address becomes valid even on a catch-all domain; a bounced one becomes invalid even if the server accepted it; domains that accept then bounce have future "valid" results downgraded. Up to 5,000 outcomes per call.

curl -X POST https://mailfloo.com/api/v1/outcomes.php \
  -H "X-Api-Key: mf_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"outcomes":[{"email":"a@acme.com","outcome":"delivered"},
                   {"email":"b@northwind.io","outcome":"bounced","note":"550 5.1.1"}]}'

Or skip the integration entirely: point your sending tool's event webhook at https://mailfloo.com/webhook/bounce.php?key=mf_live_YOUR_KEY. MailFloo understands the event formats of SendGrid, Mailgun, Brevo, Postmark and Amazon SES; delivered and bounce events are learned, everything else is ignored.

Result vocabulary

statusMeaning
validMailbox confirmed by its server, or by recorded delivery.
catch_allDomain accepts every address. score and reason carry the likelihood; reason says "likely" when pattern or history support it.
riskyDeliverable but with warning signs: a role address, or a domain that has accepted-then-bounced before.
unknownThe server would not give a usable answer after retries.
invalidRejected, malformed, dead domain, or a recorded bounce.
disposableA temporary-mailbox service.
duplicateAppeared earlier in the same list; not charged.
pendingStill being checked. Ask again in a few seconds.

confidence is the score's band: very_high (90+), high (70+), medium (40+), low. The flags catch_all, role, free_provider and disposable are booleans and travel with every result.

Limits and behaviour

  • 60 requests per minute per key; 5,000 addresses per bulk call; 5,000 outcomes per call.
  • A verdict from the last 30 days is returned from cache at no credit; fresh=1 overrides.
  • Addresses on your account's do-not-verify list are returned as suppressed and never charged.
  • Duplicates and malformed rows are never charged.
  • Results are kept 30 days, then deleted.

Questions

Does the email verification API send an email?

No. Every check is an SMTP conversation that ends before any message is sent, plus DNS and list lookups. The address owner receives nothing.

How fast is a single verification?

If the address was checked in the last 30 days the reply is immediate. Otherwise a fresh check takes a few seconds for an honest server, and up to about 25 seconds when the server greylists and a retry is needed; pass wait=1 to block for the answer.

Can I verify emails in bulk through the API?

Yes, up to 5,000 addresses per call to bulk.php. Pass a callback_url and MailFloo POSTs a summary when the job completes, or poll job.php for status and paged results.

What does the catch_all status mean in the API?

The domain accepts any address, so the server's reply alone cannot confirm the mailbox. The score and reason carry MailFloo's resolution: naming-pattern match, the server behind the gateway, and delivery history. See the catch-all guide for the full method.

How do I make verification results improve over time?

Send delivered and bounced outcomes to outcomes.php, or point your mailer's event webhook at webhook/bounce.php. Recorded outcomes override server replies on the next check and recalibrate scores.