Quickstart
Verify your first email address with the mailfloss API in under five minutes.
This is the current mailfloss API (v1). The original email-verification API (api.mailfloss.com/verify?api_key=…) is now deprecated and will sunset on June 1, 2027. Build new integrations on v1, and plan to migrate existing ones — see Authentication for the api_key → Bearer change.
1. Get your API key
Your API key lives in the mailfloss dashboard under Settings → API. It's a secret — treat it like a password, keep it server-side, and never embed it in client-side code or commit it to source control.
2. Verify a single email
Send your key as a Bearer token and call GET /v1/verify:
curl https://api.mailfloss.com/v1/[email protected] \
-H "Authorization: Bearer YOUR_API_KEY"A successful call returns the verdict directly as the response body:
{
"email": "[email protected]",
"status": "passed",
"reason": "valid",
"passed": true
}- status — the deliverability verdict for the address: passed, undeliverable, risky, or unknown.
- reason — the specific signal behind the verdict.
- passed — a convenience boolean for "safe to send."
Each successful verification consumes one credit from your account. See the API reference for the full list of status and reason values.
3. Handle errors
Errors come back in a consistent envelope — branch on the stable code, never on the human-readable message:
{
"error": {
"code": "insufficient_credits",
"message": "Your account is out of verification credits.",
"type": "billing_error",
"request_id": "req_a1b2c3"
}
}Full details in the Errors guide.
4. Verify in bulk
For lists, submit a batch job and poll for results:
# Submit
curl -X POST https://api.mailfloss.com/v1/batch-verify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "emails": ["[email protected]", "[email protected]"] }'
# -> { "id": "job_123", ... }
# Poll status
curl https://api.mailfloss.com/v1/batch-verify/job_123/status \
-H "Authorization: Bearer YOUR_API_KEY"
# Fetch results (paginated) once status is "completed"
curl https://api.mailfloss.com/v1/batch-verify/job_123/results \
-H "Authorization: Bearer YOUR_API_KEY"POST endpoints accept an optional Idempotency-Key header so a retried submit never double-charges. See the reference for the batch request shape.
Next steps
- Authentication — Bearer vs. the legacy api_key parameter, and key handling.
- Pagination — how list responses page.
- Connect an ESP — verify-first automation across 18 email platforms.
- SDKs — official typed clients for Node.js, Python, Ruby, and Go.
- API reference — every endpoint, parameter, and response shape.