mailfloss Verification API
Single-email verification endpoints
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/mailfloss:mailfloss-verification-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: mailfloss Verification API
version: 1.0.0
description: 'mailfloss email verification API — version 1.
## Authentication
Every request must include your API key as a Bearer token in the `Authorization` header:
```
Authorization: Bearer YOUR_API_KEY
```
This is the only accepted authentication scheme for v1. The legacy `?api_key=` query parameter is **not** accepted on v1 endpoints.
## Conventions
List endpoints return a `{ data, pagination }` envelope. Errors return a stable machine-readable `code` (branch on it, not the message). Timestamps are ISO 8601 UTC.'
contact:
name: mailfloss support
url: https://mailfloss.com
email: support@mailfloss.com
servers:
- url: https://api.mailfloss.com
description: Production
tags:
- name: Verification
description: Single-email verification endpoints
paths:
/v1/verify:
get:
summary: Verify a single email address
description: 'Performs email verification on a single email address and returns a deliverability verdict. Consumes one credit from the org account on success. Returns the raw engine verdict: batch results for the same address may differ, because batch verdicts have the org''s floss-settings overrides applied — see the v1 contract ("Live vs batch verdicts").'
tags:
- Verification
security:
- apiKeyHeader: []
parameters:
- schema:
type: string
description: The email address to verify.
required: false
description: The email address to verify.
name: email
in: query
- schema:
anyOf:
- type: number
- type: string
description: Optional per-request timeout, in seconds.
required: false
description: Optional per-request timeout, in seconds.
name: timeout
in: query
responses:
'200':
description: Verification verdict
content:
application/json:
schema:
type: object
properties:
email:
type: string
domain:
type: string
status:
type: string
enum:
- passed
- undeliverable
- risky
- unknown
description: 'Verification verdict. `passed` = safe to send; `undeliverable` = hard fail (no mailbox / invalid); `risky` = role, disposable, bounced, or complained (deliverable but flagged); `unknown` = could not be determined — includes accept-all/catch-all domains and transient SMTP failures. Source: server/api/checker.js. This is the raw engine verdict, with no org floss-settings overrides applied — batch-verify results for the same address may differ.'
reason:
type: string
passed:
type: boolean
role:
type: boolean
disposable:
type: boolean
free:
type: boolean
relay:
type: boolean
description: True when the address belongs to a known email relay/forwarding/masking service (e.g. Apple Hide My Email, DuckDuckGo, Firefox Relay, SimpleLogin, addy.io). Annotation only — does not change the verdict.
gibberish:
type: boolean
description: True when the local part looks random/gibberish (e.g. xk39fjqz). Conservative signup-fraud signal; annotation only — does not change the verdict.
suggestion:
type: string
meta:
type: string
required:
- email
- status
- reason
- passed
example:
email: jane@example.com
domain: example.com
status: passed
reason: valid
passed: true
role: false
disposable: false
free: false
relay: false
gibberish: false
suggestion: ''
meta: ''
'400':
description: Invalid request — a query or body parameter failed validation. Branch on `code`, not the message.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: invalid_request
message: A required parameter is missing or malformed.
type: invalid_request_error
request_id: req_1a2b3c4d5e6f
'401':
description: Authentication failed — the API key is missing, malformed, unknown, expired, or revoked. (Expired/revoked/unknown are intentionally indistinguishable.)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: invalid_api_key
message: Invalid API key.
type: authentication_error
request_id: req_1a2b3c4d5e6f
'402':
description: 'Insufficient credits to complete the request (billing_error). Future: may carry an x402 payment-instructions sibling.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: insufficient_credits
message: Your account does not have enough credits to complete this request.
type: billing_error
request_id: req_1a2b3c4d5e6f
'403':
description: Forbidden — the API key lacks the required scope, or the account is restricted (suspended / paused / banned).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: forbidden_scope
message: API key does not have the required scope.
type: authentication_error
request_id: req_1a2b3c4d5e6f
'429':
description: Rate limited — too many requests. Honor the Retry-After / X-RateLimit-* response headers.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: rate_limited
message: Rate limit exceeded. Retry after the period indicated by the Retry-After header.
type: rate_limit_error
request_id: req_1a2b3c4d5e6f
'500':
description: Unexpected server error or timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: server_error
message: An unexpected error occurred. Please retry.
type: api_error
request_id: req_1a2b3c4d5e6f
'503':
description: Service temporarily unavailable, or an upstream dependency could not be reached.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
error:
code: service_unavailable
message: The service is temporarily unavailable. Please retry shortly.
type: api_error
request_id: req_1a2b3c4d5e6f
operationId: getV1Verify
x-operation-id-source: derived
components:
schemas:
ErrorEnvelope:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code. See docs/api/v1_contract.md for the frozen enum.
message:
type: string
description: Human-readable error message. Do NOT pattern-match — use code instead.
type:
type: string
description: Coarse category derived from HTTP status (authentication_error, billing_error, invalid_request_error, rate_limit_error, not_found_error, conflict_error, api_error).
request_id:
type:
- string
- 'null'
description: Echoes the X-Request-Id response header.
required:
- code
- message
- type
- request_id
required:
- error
securitySchemes:
apiKeyHeader:
type: http
scheme: bearer
description: 'Send your API key as a Bearer token: `Authorization: Bearer <token>`. This is the only accepted authentication scheme for the v1 API.'