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-reports-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 Reports 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: Reports
description: Verification usage analytics
paths:
/v1/reports/usage:
get:
summary: Get verification usage analytics
description: Org-level verification usage for one UTC calendar period — a top-level `total`, a `statuses` breakdown (`passed`/`undeliverable`/`risky`/`unknown`, per https://docs.mailfloss.com/status-definitions) and an org-wide `reasons` breakdown (same vocabulary as GET /v1/jobs/{id}). Select with `?period=` (default `this_month`). `period=lifetime` returns the all-time `total` only — `statuses` and `reasons` are `null` (only the grand total is stored). An org with no activity returns a zeroed report (200), not 404. `total` is authoritative; the `statuses` counts may not sum exactly to it.
tags:
- Reports
security:
- apiKeyHeader: []
parameters:
- schema:
type: string
enum:
- this_week
- this_month
- this_year
- lifetime
description: Calendar period; default this_month. Unknown value → 400.
required: false
description: Calendar period; default this_month. Unknown value → 400.
name: period
in: query
- schema:
type: string
description: Scope the report to a single ESP connection (the public connection id = the flossSettings `_id` from GET /v1/integrations/{type}). Omit for an org-wide report. Per-connection data exists only for this_week / this_month / this_year — combining it with `period=lifetime` returns 400 (lifetime is org-only).
required: false
description: Scope the report to a single ESP connection (the public connection id = the flossSettings `_id` from GET /v1/integrations/{type}). Omit for an org-wide report. Per-connection data exists only for this_week / this_month / this_year — combining it with `period=lifetime` returns 400 (lifetime is org-only).
name: connection_id
in: query
responses:
'200':
description: Usage report
content:
application/json:
schema:
type: object
properties:
period:
type: string
enum:
- this_week
- this_month
- this_year
- lifetime
description: Calendar period (UTC). this_week = current Sun–Sat; this_month = current calendar month; this_year = current calendar year; lifetime = all-time total (total only — no breakdown). Default this_month.
connection_id:
type:
- string
- 'null'
description: The ESP connection this report is scoped to when `?connection_id=` was supplied; `null` for an org-wide report. Per-connection data exists only for this_week / this_month / this_year (lifetime is org-only).
range:
type:
- object
- 'null'
properties:
start:
type: string
description: Period start, YYYY-MM-DD (UTC).
end:
type: string
description: Period end, YYYY-MM-DD (UTC).
required:
- start
- end
description: UTC calendar boundaries; null for lifetime.
total:
type: integer
minimum: 0
description: Emails verified in the period (authoritative grand total).
statuses:
type:
- object
- 'null'
properties:
passed:
type: integer
minimum: 0
description: Verified-good — safe to send.
failed:
type: integer
minimum: 0
description: Everything NOT passed for the period — the dashboard's "Failed" total (undeliverable + risky + unknown). The headline "how many invalid/bad were removed this period" number; `reasons` itemizes it.
undeliverable:
type: integer
minimum: 0
description: Verified-bad — should be removed. A SUBSET of `failed`.
risky:
type: integer
minimum: 0
description: Deliverable but risky (spam-trap / role / disposable / …). A SUBSET of `failed`.
unknown:
type: integer
minimum: 0
description: Could not be determined (accept-all / unverifiable). A SUBSET of `failed`.
required:
- passed
- failed
- undeliverable
- risky
- unknown
description: Per-status counts for the period. null for lifetime.
reasons:
type:
- object
- 'null'
properties:
invalid:
type: integer
minimum: 0
nonexistent:
type: integer
minimum: 0
deactivated:
type: integer
minimum: 0
inbox_full:
type: integer
minimum: 0
illegitimate:
type: integer
minimum: 0
spam:
type: integer
minimum: 0
role_based:
type: integer
minimum: 0
banned_words:
type: integer
minimum: 0
disposable:
type: integer
minimum: 0
failed_exchange:
type: integer
minimum: 0
accept_all:
type: integer
minimum: 0
unverified:
type: integer
minimum: 0
complained:
type: integer
minimum: 0
bounced:
type: integer
minimum: 0
blacklisted:
type: integer
minimum: 0
available:
type: integer
minimum: 0
required:
- invalid
- nonexistent
- deactivated
- inbox_full
- illegitimate
- spam
- role_based
- banned_words
- disposable
- failed_exchange
- accept_all
- unverified
- complained
- bounced
- blacklisted
- available
description: Per-reason counts. Every key present; 0 when none. null for lifetime.
required:
- period
- connection_id
- range
- total
- statuses
- reasons
example:
period: this_month
connection_id: null
range:
start: '2026-06-01'
end: '2026-06-30'
total: 45000
statuses:
passed: 40000
failed: 5000
undeliverable: 3500
risky: 1200
unknown: 300
reasons:
invalid: 500
nonexistent: 1200
deactivated: 800
inbox_full: 400
illegitimate: 200
spam: 300
role_based: 150
banned_words: 100
disposable: 250
failed_exchange: 80
accept_all: 350
unverified: 200
complained: 50
bounced: 120
blacklisted: 0
available: 40000
'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
'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: getV1ReportsUsage
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.'