Create a bulk email verification job from a list of up to 10,000 addresses (data.emails). Costs 1 email verification credit per unique valid-syntax address (counts.billable), charged when the job starts; the unverified remainder is refunded on cancel or failure. The job counts the list and then starts on its own, usually within a minute; when the balance is short of counts.billable it stays awaiting_confirmation and starts once the credits are there (or with email_verifications_start). Answers 202 with the job and Location: /v2/jobs/{id}; poll it, or subscribe once to job.finished with POST /v2/webhooks, then read GET /v2/email-verifications/{id}/results (one item per address in request order). data.file_key (an uploaded file) is for the App: that job parks at awaiting_confirmation for email_verifications_start. With an Idempotency-Key, a retry of the same request answers the job it created instead of creating another. 1 jobs rate-limit unit.

How are credits spent?

1 email verification credit per unique valid-syntax address, charged when the job starts; the unverified remainder is refunded on cancel or failure. Duplicates and addresses with invalid syntax are free.

How the job works

Send up to 10,000 addresses in data.emails. The answer is 202 with the job and Location: /v2/jobs/{id}. The job first counts the list, then starts on its own, usually within a minute. If the balance is short of the billable count, it waits in awaiting_confirmation and starts once the credits are there.

When it is done, page Get Email Verification Results: one item per address in request order (a duplicate appears at each of its positions) with status, provider, domain and free_email. Addresses with invalid syntax come back invalid without being checked.

Poll the job or subscribe to job.finished as described in Bulk jobs: poll or webhook. data.file_key is for files uploaded in the app; use data.emails from the API.

Body parameters

• dataobjectrequired

  What to verify: a list of addresses (emails), or in the App an uploaded file (file_key).

  Field	Type	Description
  emails	string[]	The addresses to verify, 1-10,000, each at most 320 characters. Exactly one of emails / file_key. The job starts on its own once counted; repeated addresses are charged once and answered at each position in GET /v2/email-verifications/{id}/results. Example: ["emily.carter.sample@intercom.com","liam.novak.sample@getprospect.com"]
  file_key	string	App only: the S3 key on the imports bucket, as returned by the /aws/pre-signed upload flow. Exactly one of emails / file_key. The job parks at awaiting_confirmation for email_verifications_start. max length: 512.
  name	string	Display name; defaults to the uploaded file's name, or to the date for emails. max length: 128.
  email_column	integer	With file_key only. Zero-based index of the email column (from inspect), range-checked against the file. Optional: without it the one column that holds addresses is used; a file with none or several answers 400 missing_field with email_column_candidates in payload. min: 0.
  source	enum	With file_key only: how the emails arrived - a paste still uploads a generated CSV. Defaults to file; a job from emails reads source: api. Allowed values: file paste

Responses

• 202 The job, queued.
• 400 Invalid body or Idempotency-Key: both or neither of emails / file_key (conflicting_fields / missing_field), more than 10,000 or a blank address, or, with file_key, an unreadable or empty file, email_column out of range, or no email_column for a file with none or several address columns (VALIDATION_ERROR, missing_field with email_column_candidates).
• 401 Missing, unknown or inactive credentials (UNAUTHORIZED).
• 403 The file belongs to another workspace (FORBIDDEN).
• 409 The Idempotency-Key was used for another request (CONFLICT, idempotency_key_reused).
• 429 Over the jobs rate limit (RATE_LIMIT); wait Retry-After seconds. Sent only where rate limits are enforced for the caller channel.
• 500 Unexpected server error.

For error handling see Errors.