Verification lists
Verify up to 10,000 addresses at once and export the results.
Create a list
Creates a verification list and starts verifying its addresses in the background. Every address is checked in full mode, including the mailbox check described in Verify an address. Requires an API key with full scope.
/email-verification-listsRequest body
namestringRequiredList name, 1 to 255 characters.
emailsstring[]RequiredAddresses to verify, 1 to 10,000. Every item must be a valid email address. Emailit trims and lowercases them and removes duplicates.
Returns
Returns 201 Created with the list. Emailit charges 5 credits per unique address before verification starts. The response reports how many addresses were accepted (valid_emails_count, unique_emails_count) and how many verification jobs were queued (dispatched_jobs). The new list has the status processing.
stats is updated as each address finishes. When every address has a final result, the list moves to completed. Poll Retrieve a list or listen for webhook events:
email_verification_list.createdwhen the list is created.email_verification.updatedfor each address as it finishes.email_verification_list.updatedwhen the list is completed.
| Status | When |
|---|---|
400 |
name or emails is missing or empty, emails has more than 10,000 items, or an item isn’t a valid address (standard validation error). |
402 |
The workspace doesn’t have enough credits for every unique address. |
Stats
| Field | Description |
|---|---|
total_emails |
Unique addresses in the list. |
processed_emails |
Addresses that finished, with a result or an error. |
successful_verifications |
Addresses with a final result, whatever the result is. This doesn’t mean the addresses are valid; see results. |
failed_verifications |
Addresses an error stopped Emailit from checking. |
pending_emails |
Addresses not finished yet, including ones waiting for a greylisting retry. |
results |
Finished addresses by result: safe, role, catch_all, unknown, inbox_full, disabled, disposable and invalid. Older lists may not have it. |
{
"id": "evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a",
"name": "October newsletter import",
"valid_emails_count": 2,
"unique_emails_count": 2,
"invalid_emails_count": 0,
"status": "processing",
"dispatched_jobs": 2,
"stats": {
"total_emails": 2,
"processed_emails": 0,
"successful_verifications": 0,
"failed_verifications": 0,
"pending_emails": 2,
"results": {
"safe": 0,
"role": 0,
"catch_all": 0,
"unknown": 0,
"inbox_full": 0,
"disabled": 0,
"disposable": 0,
"invalid": 0
}
},
"created_at": "2026-10-01T10:30:02.441000+00:00"
}{
"statusCode": 402,
"error": "Payment Required",
"message": "Insufficient credits for email verification list."
}List lists
Returns your email verification lists, newest first. Requires an API key with full scope.
/email-verification-listsQuery parameters
pageintegerPage number, starting at 1. Default 1.
limitintegerLists per page, from 1 to 100. Default 10.
statusstringOnly lists with this status: pending, processing, completed, failed or canceled.
searchstringCase-insensitive match on the list name.
matchstringall (default) requires every filter. or matches any filter. See Filtering.
orderstringSort key for this list. See the sort keys below.
directionstringasc or desc.
Filters and sort
List filters are one layer of key.condition=value query parameters. See Filtering for match, order, direction and the condition list per type.
Filter keys
| Key | Type | Conditions | Notes |
|---|---|---|---|
name | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
status | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
created_at | date | exact, before, after, empty, not_empty |
Sort keys
Pass order as one of these keys and direction as asc or desc: name, status, created_at
Returns
Returns 200 OK with the lists in data, plus next_page_url and previous_page_url (null at either end). Each list has id, name, status, stats, created_at and updated_at; see Create a list for the stats fields.
{
"data": [
{
"id": "evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a",
"name": "October newsletter import",
"status": "completed",
"stats": {
"total_emails": 1000,
"processed_emails": 1000,
"successful_verifications": 996,
"failed_verifications": 4,
"pending_emails": 0,
"results": {
"safe": 702,
"role": 41,
"catch_all": 88,
"unknown": 37,
"inbox_full": 3,
"disabled": 6,
"disposable": 12,
"invalid": 107
}
},
"created_at": "2026-10-01T10:30:02.441000+00:00",
"updated_at": "2026-10-01T10:41:57.020000+00:00"
}
],
"next_page_url": "/v2/email-verification-lists?page=2&limit=10",
"previous_page_url": null
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid API key"
}Retrieve a list
Returns one email verification list. Poll it to find out when a list is completed, or listen for the email_verification_list.updated webhook event instead. Requires an API key with full scope.
/email-verification-lists/:idPath parameters
idstringRequiredList ID, for example evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a.
Returns
Returns 200 OK with the list’s id, name, status, stats, created_at and updated_at. stats is updated as each address finishes, so you can follow a processing list’s progress. See Create a list for the stats fields.
Returns 404 if the list doesn’t exist in your workspace.
{
"id": "evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a",
"name": "October newsletter import",
"status": "completed",
"stats": {
"total_emails": 1000,
"processed_emails": 1000,
"successful_verifications": 996,
"failed_verifications": 4,
"pending_emails": 0,
"results": {
"safe": 702,
"role": 41,
"catch_all": 88,
"unknown": 37,
"inbox_full": 3,
"disabled": 6,
"disposable": 12,
"invalid": 107
}
},
"created_at": "2026-10-01T10:30:02.441000+00:00",
"updated_at": "2026-10-01T10:41:57.020000+00:00"
}{
"statusCode": 404,
"error": "Not Found",
"message": "Email verification list not found"
}List results
Returns one result per address in a verification list, most recently updated first. Results appear as addresses finish, so you can read them before the whole list completes. Requires an API key with full scope.
/email-verification-lists/:id/resultsPath parameters
idstringRequiredList ID, for example evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a.
Query parameters
pageintegerPage number, starting at 1. Default 1.
limitintegerResults per page, from 1 to 100. Default 50.
statusstringOnly results with this status: pending, processing, completed, failed or canceled.
resultstringOnly results with this outcome: safe, role, catch_all, unknown, inbox_full, disabled, disposable or invalid.
matchstringall (default) requires every filter. or matches any filter. See Filtering.
orderstringSort key for this list. See the sort keys below.
directionstringasc or desc.
Filters and sort
List filters are one layer of key.condition=value query parameters. See Filtering for match, order, direction and the condition list per type.
Filter keys
| Key | Type | Conditions | Notes |
|---|---|---|---|
email | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
status | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
result | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
risk | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
created_at | date | exact, before, after, empty, not_empty |
Sort keys
Pass order as one of these keys and direction as asc or desc: email, status, result, risk, created_at
Returns
Returns 200 OK with the results in data, plus next_page_url and previous_page_url (null at either end). Each result is an email_verification object with the same fields as Verify an address returns: id (evr_…), email, status, result, score, risk, mode, checks, address, did_you_mean, mx_records and timestamps. An address that’s still pending or processing has no final result yet. One an error stopped has the status failed and the result error; find those with status=failed.
Returns 404 if the list doesn’t exist in your workspace.
{
"data": [
{
"id": "evr_2xLeA1Pn6Rw3Ks8Vb0Ht5Mq2Fd9c",
"object": "email_verification",
"email": "ada@example.com",
"status": "completed",
"score": 100,
"risk": "low",
"result": "safe",
"mode": "full",
"checks": {
"valid_syntax": true,
"disposable": false,
"role_account": false,
"inbox_full": false,
"deliverable": true,
"disabled": false,
"catch_all": false,
"free_email": false,
"smtp_connect": true,
"has_mx_records": true,
"domain_age": 10957,
"gibberish": false
},
"address": {
"mailbox": "ada",
"domain": "example.com",
"suffix": null,
"root": "ada@example.com"
},
"did_you_mean": null,
"mx_records": [
{ "priority": 10, "exchange": "mx1.example.com" }
],
"created_at": "2026-10-01T10:30:02.441000+00:00",
"updated_at": "2026-10-01T10:30:09.876000+00:00"
},
{
"id": "evr_2xLeA2Qm7Sx4Lt9Wc1Ju6Nr3Ge0d",
"object": "email_verification",
"email": "grace@example.com",
"status": "completed",
"score": 0,
"risk": "high",
"result": "invalid",
"mode": "full",
"checks": {
"valid_syntax": true,
"disposable": false,
"role_account": false,
"inbox_full": false,
"deliverable": false,
"disabled": false,
"catch_all": false,
"free_email": false,
"smtp_connect": true,
"has_mx_records": true,
"domain_age": 10957,
"gibberish": false
},
"address": {
"mailbox": "grace",
"domain": "example.com",
"suffix": null,
"root": "grace@example.com"
},
"did_you_mean": null,
"mx_records": [
{ "priority": 10, "exchange": "mx1.example.com" }
],
"created_at": "2026-10-01T10:30:02.441000+00:00",
"updated_at": "2026-10-01T10:30:08.112000+00:00"
}
],
"next_page_url": "/v2/email-verification-lists/evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a/results?page=2&limit=50",
"previous_page_url": null
}{
"statusCode": 404,
"error": "Not Found",
"message": "Email verification list not found"
}Export results
Downloads the results of a verification list as an XLSX spreadsheet. The list must be completed first. Requires an API key with full scope.
/email-verification-lists/:id/exportPath parameters
idstringRequiredList ID, for example evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a.
Returns
Returns 200 OK with the file as the response body, Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet and a Content-Disposition: attachment header. The file is named after the list ID, for example evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a.xlsx.
| Status | When |
|---|---|
400 |
The list isn’t completed yet. |
404 |
The list doesn’t exist in your workspace, or it has no results to export. |
HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a.xlsx"
<binary XLSX data>{
"statusCode": 400,
"error": "Bad Request",
"message": "Cannot export incomplete list. List must be completed first."
}{
"statusCode": 404,
"error": "Not Found",
"message": "Email verification list not found"
}