API Reference

Email Verifier API

v0.1.0

Professional email verification API. ## Authentication Every request must carry your API key in the **`Api-Key`** header (never `Authorization: Bearer`). Keys are prefixed with `ev_`. ``` Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx ``` ## Rate limiting Limits are enforced **per key**. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix epoch). On `429` a `Retry-After` header (seconds) is also returned. ## Billing & quota One verification = one credit. Results categorised as `unknown` are **never** billed; in bulk, the unit is distinct addresses after de-duplication. The monthly quota is a **soft cap** by default (usage is measured and you are alerted, but requests are never blocked). When a client is configured with `hard_cap=true`, exhausting the quota returns `402 QUOTA_EXCEEDED`. Track your own consumption via `GET /usage`. ## Error format Errors return an HTTP status and a JSON body of the shape: ```json { "detail": { "error": "Human-readable message.", "code": "MACHINE_CODE" } } ``` Always branch on the stable `code`, not on the message text.

GET /api/v1/health

Health Check

Responses

Status	Description
200	Successful Response object

GET /api/v1/

Root

Responses

Status	Description
200	Successful Response any

GET /api/v1/stats/disposable

Disposable Stats

Return stats about disposable domain detection.

Responses

Status	Description
200	Successful Response any

GET /api/v1/stats/free-providers

Free Provider Stats

Return stats about free email provider detection.

Responses

Status	Description
200	Successful Response any

GET /api/v1/stats/internal-cache

Internal Cache Stats

Return stats about the internal cache (hard bounces, high-risk emails).

Responses

Status	Description
200	Successful Response any

GET /api/v1/stats/verification-history

Verification History Stats

Return stats about the verification history table (Phase 3.1). This is the global, client-agnostic store of stable verdicts (undeliverable/disposable/high_risk) with 5-year retention.

Responses

Status	Description
200	Successful Response any

POST /api/v1/verify

Verify Single Email

Request Body *

application/json

Field	Type	Description	Default
`email` *	string
`options`	object \| null

Responses

Status	Description
200	Successful Response object
401	Missing, invalid, revoked or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, KEY_EXPIRED.
402	Monthly quota exhausted (only when the client has hard_cap=true).
403	API key lacks the required scope, or the client account is inactive. Codes: INSUFFICIENT_SCOPE, CLIENT_INACTIVE.
422	Validation Error object
429	Per-key rate limit exceeded.

POST /api/v1/verify/batch

Verify Batch Emails

Enqueue a batch of emails (up to 1000) for asynchronous verification. Returns a 202 with a `job_id` the client can poll via `GET /jobs/{id}`.

Request Body *

application/json

Field	Type	Description	Default
`emails` *	array[string]
`options`	object \| null
`webhook_url`	string \| null	HTTPS URL to notify when the job completes.
`retention_days`	integer	Number of days the result CSV is kept available for download. Must be between 1 and 30. The retention period must be between 1 and 30 days.	`1`

Responses

Status	Description
202	Successful Response object
400	Invalid request. Codes: BATCH_TOO_LARGE, INVALID_RETENTION_DAYS.
401	Missing, invalid, revoked or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, KEY_EXPIRED.
403	API key lacks the required scope, or the client account is inactive. Codes: INSUFFICIENT_SCOPE, CLIENT_INACTIVE.
422	Validation Error object
429	Per-key rate limit exceeded.

POST /api/v1/verify/csv

Verify Csv Upload

Upload a CSV file (up to 100 000 rows) for asynchronous batch verification. Auto-detects encoding (UTF-8/UTF-8-BOM/CP1252/Latin-1), delimiter (`,;\t|`), header presence, and the email column. Extra columns are preserved in the output CSV.

Request Body *

multipart/form-data

Field	Type	Description	Default
`file` *	string	CSV file. Max size: csv_max_file_size_mb, max rows: csv_max_rows.
`webhook_url`	string \| null	HTTPS URL to notify when the job completes.
`retention_days`	integer	Days the result CSV is kept (1–30, default 1).	`1`
`check_smtp`	boolean		`true`
`suggest_typo`	boolean		`true`
`check_random`	boolean		`true`
`check_domain_trust`	boolean		`false`

Responses

Status	Description
202	Successful Response object
400	Invalid file/content. Codes: INVALID_RETENTION_DAYS, EMPTY_FILE, CSV_PARSE_ERROR, EMPTY_CSV, TOO_MANY_ROWS, UPLOAD_FAILED.
401	Missing, invalid, revoked or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, KEY_EXPIRED.
403	API key lacks the required scope, or the client account is inactive. Codes: INSUFFICIENT_SCOPE, CLIENT_INACTIVE.
413	Uploaded CSV exceeds the maximum allowed size.
422	Validation Error object
429	Per-key rate limit exceeded.

GET /api/v1/jobs

List Jobs

List verification jobs (most recent first). Currently returns all jobs in the system (admin view). Phase 5 will add per-client filtering based on the authenticated client_id.

Parameters

Name	In	Type	Description
`status`	query	string \| null	Filter by status: pending, processing, completed, failed, cancelled
`created_after`	query	string \| null	ISO 8601 timestamp - only jobs created after this date
`created_before`	query	string \| null	ISO 8601 timestamp - only jobs created before this date
`limit`	query	integer
`offset`	query	integer

Responses

Status	Description
200	Successful Response object
400	Invalid query filter. Codes: INVALID_STATUS_FILTER, INVALID_DATE_FORMAT.
401	Missing, invalid, revoked or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, KEY_EXPIRED.
403	API key lacks the required scope, or the client account is inactive. Codes: INSUFFICIENT_SCOPE, CLIENT_INACTIVE.
422	Validation Error object

GET /api/v1/jobs/{job_id}

Get Job Status

Fetch the status and stats of a verification job.

Parameters

Name	In	Type	Description
`job_id` *	path	string

Responses

Status	Description
200	Successful Response object
400	Malformed job_id.
401	Missing, invalid, revoked or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, KEY_EXPIRED.
403	API key lacks the required scope, or the client account is inactive. Codes: INSUFFICIENT_SCOPE, CLIENT_INACTIVE.
404	No job with this id for the authenticated client.
422	Validation Error object

GET /api/v1/jobs/{job_id}/results

Get Job Results

Get a paginated page of results for a completed (or in-progress) job.

Parameters

Name	In	Type	Description
`job_id` *	path	string
`offset`	query	integer
`limit`	query	integer
`category`	query	string \| null	Filter by category: deliverable, undeliverable, risky, disposable, unknown, duplicate, invalid_syntax, random_pattern, high_risk, accept_all.
`include_email`	query	boolean	If true, decrypt and include the email address in each row.

Responses

Status	Description
200	Successful Response object
400	Malformed job_id.
401	Missing, invalid, revoked or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, KEY_EXPIRED.
403	API key lacks the required scope, or the client account is inactive. Codes: INSUFFICIENT_SCOPE, CLIENT_INACTIVE.
404	No job with this id for the authenticated client.
422	Validation Error object

GET /api/v1/jobs/{job_id}/download

Download Job Result

Download the result CSV file for a completed job. Authentication is mandatory via the `Api-Key` header. Ownership is enforced by matching the job's `client_id`.

Parameters

Name	In	Type	Description
`job_id` *	path	string

Responses

Status	Description
200	Successful Response any
400	Malformed job_id.
401	Missing, invalid, revoked or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, KEY_EXPIRED.
403	API key lacks the required scope, or the client account is inactive. Codes: INSUFFICIENT_SCOPE, CLIENT_INACTIVE.
404	Job or result file not found. Codes: JOB_NOT_FOUND, RESULT_FILE_MISSING.
409	Job is not completed yet.
410	Result file expired (past its retention window).
422	Validation Error object

GET /api/v1/usage

Read Usage

Parameters

Name	In	Type	Description
`period`	query	string \| null	Month 'YYYY-MM' (default: current month).

Responses

Status	Description
200	Successful Response any
401	Missing, invalid, revoked or expired API key. Codes: MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, KEY_EXPIRED.
403	API key lacks the required scope, or the client account is inactive. Codes: INSUFFICIENT_SCOPE, CLIENT_INACTIVE.
422	Validation Error object