Bulk validation

Verify a whole address list in one wemail API job: upload the addresses, poll the job, then download per-address verdicts as CSV or fetch them by id.

Submit up to 500,000 addresses as a JSON body or a CSV upload. The job runs asynchronously — poll the job or receive a completion webhook, then download the results.

POST /v3/validate/bulk

Body parameters

Parameter	Type	Required	Description
`emails`	array of strings	Optional	Provide EITHER this JSON array OR a CSV `file`. 1 to 500,000 addresses (each max 320 chars). Duplicates are removed before the job is queued.
`file`	multipart CSV	Optional	Alternative to the JSON `emails` array: upload a CSV (first column = email, up to 100 MB) as a multipart `file` field. Sending a file switches the request to `multipart/form-data`.
`filename`	string	Optional	Display name in job listings and exports. Default `bulk_verify.csv`.
`webhook_url`	string (URL)	Optional	POSTed the signed job summary when the job finishes.

Responses

Status	Description
`202`	Accepted. `{ job_id, status, total_count }` — the job runs asynchronously.
`400`	Empty list, more than 500,000 addresses, or an unreadable CSV upload.
`401`	Missing or invalid API key.
`402`	Insufficient credits. A live job costs 1 verification credit per deduped address; the whole charge is taken up front and the account's balance is lower than the job needs. Buy a credit pack and retry. Test keys are exempt.
`429`	The 10 jobs/min bulk limit or your account request rate was exceeded.

Working with the job

Poll it with GET /v3/validate/bulk/{jobId} (Get a bulk job), page its rows with GET /v3/validate/bulk/{jobId}/results (Results & statuses), export the CSV with GET /v3/validate/bulk/{jobId}/download (Download bulk results), and remove it from listings with DELETE /v3/validate/bulk/{jobId} (Delete a bulk job). For an instant, free hygiene score without probing, see Evaluate list quality.

Code examples

cURL

curl -X POST https://api.wemail.io/v3/validate/bulk \
  -H "Authorization: Bearer afn_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "emails": [ "a@example.com", "b@example.com" ], "filename": "list.csv", "webhook_url": "https://yourapp.com/bulk-hook" }'

Node.js

const res = await fetch("https://api.wemail.io/v3/validate/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WEMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ "emails": [ "a@example.com", "b@example.com" ], "filename": "list.csv", "webhook_url": "https://yourapp.com/bulk-hook" }),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.wemail.io/v3/validate/bulk",
    headers={"Authorization": f"Bearer {os.environ['WEMAIL_API_KEY']}"},
    json={ "emails": [ "a@example.com", "b@example.com" ], "filename": "list.csv", "webhook_url": "https://yourapp.com/bulk-hook" },
)
data = r.json()