Get verification usage analytics

GET

/v1/reports/usage

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.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Query Params

Responses

🟢200

application/json

Usage report

Bodyapplication/json

🟠400

🟠401

🟠403

🟠429

🔴500

🔴503

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.mailfloss.com/v1/reports/usage?period=&connection_id=' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Success

{
    "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
    }
}

Modified at 2026-10-20 13:54:45

Get a team member

List webhook subscriptions