Endpoints Reference

The complete parameter and error reference for every endpoint.

POST /v1/email/check

Checks a single address and returns a result synchronously.

Parameter	Type	Default	Notes
email	string	required	Max 320 characters
mode	"fast" \| "standard" \| "full"	"standard"	See Choosing a Mode for tradeoffs
context	"generic" \| "signup" \| "b2b_lead" \| "crm" \| "marketplace" \| "payment"	"generic"	Changes signal weighting — see Email Risk Scoring Explained

Returns 200 with the full result object on success — see Getting Started for the complete response shape.

POST /v1/email/bulk

Submits a batch of addresses for asynchronous processing. Returns immediately with a job reference.

Parameter	Type	Default	Notes
emails	string[]	required	Non-empty array
mode	"fast" \| "standard" \| "full"	"standard"	Applies to every address in the batch
context	same enum as above	"generic"	Applies to every address in the batch

response.json (202 Accepted)

{ "job_id": "job_9f3a2e", "status": "queued", "total": 3 }

GET /v1/email/bulk

Lists your bulk jobs, most recent first - the same view the dashboard's Bulk check page uses to show past and in-progress jobs without needing a job ID up front.

Parameter	Type	Default	Notes
page	integer	1	20 jobs per page

response.json

{
  "page": 1,
  "page_size": 20,
  "total": 3,
  "data": [
    { "job_id": "job_9f3a2e", "status": "completed", "total": 3, "processed": 3, "allow": 2, "review": 1, "block": 0, "errors": 0, "mode": "standard", "context": "generic", "created_at": "2026-08-18T09:00:00.000Z", "completed_at": "2026-08-18T09:00:12.000Z" }
  ]
}

GET /v1/email/bulk/:jobId

response.json

{
  "job_id": "job_9f3a2e",
  "status": "queued" | "processing" | "completed" | "failed",
  "total": 3,
  "processed": 3,
  "allow": 2,
  "review": 1,
  "block": 0,
  "errors": 0,
  "mode": "standard",
  "context": "generic",
  "created_at": "2026-08-18T09:00:00.000Z",
  "completed_at": "2026-08-18T09:00:12.000Z"
}

GET /v1/email/bulk/:jobId/results?page=1

response.json

{
  "job_id": "job_9f3a2e",
  "page": 1,
  "page_size": 50,
  "total": 3,
  "data": [
    { "row": 1, "email": "a@example.com", "status": "completed", "decision": "allow", "risk_score": 5, "risk_level": "low", "error": null }
  ]
}

Webhook delivery

Register a webhook endpoint from the dashboard (see Authentication — webhook management is session-authenticated, not API-key-authenticated). Once registered, a bulk job firing bulk.completed or bulk.failed will POST to your endpoint:

webhook-payload.json

{ "event": "bulk.completed", "job_id": "job_9f3a2e", "total": 3, "allow": 2, "review": 1, "block": 0 }

Every delivery includes an X-Webhook-Event header (the event name) and an X-Webhook-Signature header — an HMAC-SHA256 hex digest of the raw request body, signed with the secret shown once when you created the endpoint. See the webhook security section of Error Handling & Webhooks for how to verify it.

Error codes

Every error follows the same shape: { "error": { "code", "message", "request_id" } }.

Code	HTTP status	Meaning
INVALID_REQUEST	400	Malformed body — missing/invalid email, empty emails array, etc.
INVALID_EMAIL	400	The email field failed validation
AUTHENTICATION_REQUIRED	401	Missing or malformed Authorization header
INVALID_API_KEY	401	Key not recognized
API_KEY_REVOKED	401	Key was valid but has since been revoked
TEST_KEY_EMAIL_RESTRICTED	403	A test-mode key was used to check an address other than the account's own signup email
FORBIDDEN	403	Authenticated, but not permitted to perform this action
NOT_FOUND	404	Resource (e.g. a bulk job) doesn't exist or doesn't belong to you
CONFLICT	409	State conflict on the requested resource
RATE_LIMIT_EXCEEDED	429	Too many requests per second for your plan — back off and retry
QUOTA_EXCEEDED	402	Monthly check quota exhausted
BULK_LIMIT_EXCEEDED	400	Batch exceeds your plan's bulk allowance, or bulk isn't enabled on your plan
SERVICE_UNAVAILABLE	503	A required dependency isn't available
INTERNAL_ERROR	500	Unexpected server error — safe to retry with backoff