POST /v1/verify/batch

Verify up to 500,000 emails asynchronously. Use this for cleaning existing lists, not for real-time signup flows.

POSThttps://api.mailbeam.dev/v1/verify/batch

Submit a batch of emails. Returns a job_id immediately; use GET /v1/jobs/:id to poll status.

Request body

Parameters

Name	Type	Required	Description
`emails`	string[]	required	Array of email addresses. Maximum 500,000 per batch.
`webhook_url`	string	optional	HTTPS URL to call when the job completes.
`notify_email`	boolean	optional (default: true)	Send email notification on completion.

Submit response

Response201 Created

{
  "job_id": "job_01hx9xyz456",
  "status": "queued",
  "total": 5000,
  "created_at": "2025-01-15T14:32:00Z"
}

GET /v1/jobs/:id

GEThttps://api.mailbeam.dev/v1/jobs/:id

Poll the status of a batch job. Results available when status is 'completed'.

Response — completed200 OK

{
  "job_id": "job_01hx9xyz456",
  "status": "completed",
  "total": 5000,
  "processed": 5000,
  "valid": 4213,
  "invalid": 787,
  "completed_at": "2025-01-15T14:36:48Z",
  "download_url": "https://api.mailbeam.dev/v1/jobs/job_01hx9xyz456/results"
}

See Webhooks for how to receive completion events instead of polling.