Batch verification

Verify several email addresses in one API call with POST /v1/verify/batch, up to the batch size of your plan, then fetch the results.

Endpoint

POST https://api.kawaa.com/v1/verify/batch

Request body

{
  "emails": [
    "john@example.com",
    "jane@example.com",
    "bob@company.org"
  ]
}

Limits

The number of emails one request may carry depends on your plan:

• Free: up to 100 emails per batch request
• Starter: up to 1,000 emails per batch request
• Professional: up to 5,000 emails per batch request
• Business: up to 5,000 emails per batch request
• Enterprise: up to 10,000 emails per batch request
• The File Upload API has the same per-plan limit, so a longer list is sent as several requests. A request over the limit is refused with 413 BATCH_SIZE_EXCEEDED before anything is charged
• A batch holds 1 credit for each unique, well-formed address in it when the job is accepted; a row answered from the 24-hour result cache settles at 0.5 credits, the difference refunded when the job finishes

Response

Batch verification is asynchronous. The endpoint returns 202 Accepted with a job id. It does not return results inline:

{
  "success": true,
  "data": {
    "job_id": "8d005380-7e75-4cfe-a9ab-6abcf44652b7",
    "status": "processing",
    "total_submitted": 3,
    "duplicates_removed": 0,
    "invalid_emails_skipped": 0,
    "unique_emails": 3,
    "estimated_time_seconds": 6,
    "credits_used": 3,
    "credits_remaining": 9991,
    "message": "Batch verification started. Use GET /v1/jobs/{job_id} to check status."
  }
}

Getting the results

Poll GET /v1/jobs/{job_id} until data.status is one of the finished statuses (completed, failed or cancelled), then read the per-email results from that response. Stop on all three: a loop that waits only for completed never ends for a job that failed or was cancelled. A cancelled job still returns the addresses it checked before it stopped. Duplicate addresses are removed before billing, so credits_used reflects unique_emails rather than the number you submitted.

Instead of polling, you can be notified: subscribe an account webhook to both job.completed and job.failed, and every job that finishes on its own reaches you. A cancelled job sends no webhook; the response to your cancel request is the notice. A per-job webhook_url in the request (with a webhook_secret to sign it) is sent when the job completes or fails, and its event field says which. Webhooks shows the payload and how to check its signature.