# Verification lists API

> Verify up to 10,000 addresses at once and export the results.

Base URL: `https://api.emailit.com/v2`. Authenticate with `Authorization: Bearer <API key>`.

## Create a list — POST /email-verification-lists

> Verify up to 10,000 addresses in one request. Emailit removes duplicates, charges 5 credits per unique address and checks each one in full mode.

# 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](/docs/api-reference/email-verifications/verify/). Requires an API key with `full` scope.

`POST /email-verification-lists`

## Request body

- `name` (string, required): List name, 1 to 255 characters.

- `emails` (string[], required): Addresses 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` keeps its starting values until every address is done; then the list moves to `completed` with its final counts. Poll [Retrieve a list](/docs/api-reference/email-verifications/lists/get/) or listen for webhook events:

- [`email_verification_list.created`](/docs/webhooks/events/email-verification-list/created/) when the list is created.
- [`email_verification.updated`](/docs/webhooks/events/email-verification/updated/) for each address as it finishes.
- [`email_verification_list.updated`](/docs/webhooks/events/email-verification-list/updated/) when 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, successfully or not. |
| `successful_verifications` | Addresses verified successfully. |
| `failed_verifications` | Addresses whose verification failed with an error. |
| `pending_emails` | Addresses not processed yet. |

**Request** `POST /email-verification-lists`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const list = await emailit.emailVerificationLists.create({ name: 'October newsletter import', emails: ['ada@example.com', 'grace@example.com'] });
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

vlist = client.email_verification_lists.create({"name": "October newsletter import", "emails": ["ada@example.com", "grace@example.com"]})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$list = $emailit->emailVerificationLists()->create(['name' => 'October newsletter import', 'emails' => ['ada@example.com', 'grace@example.com']]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

list = client.email_verification_lists.create(name: "October newsletter import", emails: ["ada@example.com", "grace@example.com"])
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

list, err := client.EmailVerificationLists.Create(&emailit.CreateEmailVerificationListRequest{Name: "October newsletter import", Emails: []string{"ada@example.com", "grace@example.com"}})
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let list = emailit.email_verification_lists.create(emailit::types::CreateEmailVerificationListParams::new("October newsletter import", vec!["ada@example.com".into(), "grace@example.com".into()])).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject list = emailit.emailVerificationLists().create(EmailVerificationListCreateParams.builder().setName("October newsletter import").setEmails(Arrays.asList("ada@example.com", "grace@example.com")).build());
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var list = emailit.EmailVerificationLists.Create(new EmailVerificationListCreateOptions { Name = "October newsletter import", Emails = new[] { "ada@example.com", "grace@example.com" } });
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$list = Emailit::emailVerificationLists()->create(['name' => 'October newsletter import', 'emails' => ['ada@example.com', 'grace@example.com']]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/email-verification-lists \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "October newsletter import", "emails": ["ada@example.com", "grace@example.com"]}'
```

**201**

```json
{
  "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
  },
  "created_at": "2026-10-01T10:30:02.441000+00:00"
}
```

**402**

```json
{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Insufficient credits for email verification list."
}
```

---
Source: https://emailit.com/docs/api-reference/email-verifications/lists/create/

## List lists — GET /email-verification-lists

> List the email verification lists in your workspace with their status and counts, filtered by status, name or date.

# List lists

Returns your email verification lists, newest first. Requires an API key with `full` scope.

`GET /email-verification-lists`

## Query parameters

- `page` (integer): Page number, starting at `1`. Default `1`.

- `limit` (integer): Lists per page, from `1` to `100`. Default `10`.

- `status` (string): Only lists with this status: `pending`, `processing`, `completed`, `failed` or `canceled`.

- `search` (string): Case-insensitive match on the list name.

- `match`, `order`, `direction`: see [Filtering](https://emailit.com/docs/api-reference/filtering/).

## Filters and sort

Filter and sort keys: see [Filtering](https://emailit.com/docs/api-reference/filtering/).

## 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](/docs/api-reference/email-verifications/lists/create/) for the `stats` fields.

**Request** `GET /email-verification-lists`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const lists = await emailit.emailVerificationLists.list();
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

vlists = client.email_verification_lists.list()
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$lists = $emailit->emailVerificationLists()->list();
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

lists = client.email_verification_lists.list
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

lists, err := client.EmailVerificationLists.List(nil)
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let lists = emailit.email_verification_lists.list(None).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject lists = emailit.emailVerificationLists().list();
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var lists = emailit.EmailVerificationLists.List();
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$lists = Emailit::emailVerificationLists()->list();
```

**cURL**

```bash
curl -X GET https://api.emailit.com/v2/email-verification-lists \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"
```

**200**

```json
{
  "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
      },
      "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
}
```

**401**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

---
Source: https://emailit.com/docs/api-reference/email-verifications/lists/list/

## Retrieve a list — GET /email-verification-lists/{id}

> Retrieve an email verification list by its ID to check its status and verification counts while it runs and after it completes.

# 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`](/docs/webhooks/events/email-verification-list/updated/) webhook event instead. Requires an API key with `full` scope.

`GET /email-verification-lists/:id`

## Path parameters

- `id` (string, required): List ID, for example `evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a`.

## Returns

Returns `200 OK` with the list's `id`, `name`, `status`, `stats`, `created_at` and `updated_at`. While a list is `processing`, `stats` shows its starting values; the final counts are written when it completes. See [Create a list](/docs/api-reference/email-verifications/lists/create/) for the `stats` fields.

Returns `404` if the list doesn't exist in your workspace.

**Request** `GET /email-verification-lists/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const list = await emailit.emailVerificationLists.get('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

vlist = client.email_verification_lists.get("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$list = $emailit->emailVerificationLists()->get('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

list = client.email_verification_lists.get("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

list, err := client.EmailVerificationLists.Get("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a")
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let list = emailit.email_verification_lists.get("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a").await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject list = emailit.emailVerificationLists().get("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var list = emailit.EmailVerificationLists.Get("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$list = Emailit::emailVerificationLists()->get('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a');
```

**cURL**

```bash
curl -X GET https://api.emailit.com/v2/email-verification-lists/evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"
```

**200**

```json
{
  "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
  },
  "created_at": "2026-10-01T10:30:02.441000+00:00",
  "updated_at": "2026-10-01T10:41:57.020000+00:00"
}
```

**404**

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Email verification list not found"
}
```

---
Source: https://emailit.com/docs/api-reference/email-verifications/lists/get/

## List results — GET /email-verification-lists/{id}/results

> List the verification result for each address in an email verification list, filtered by status, result or risk.

# 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.

`GET /email-verification-lists/:id/results`

## Path parameters

- `id` (string, required): List ID, for example `evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a`.

## Query parameters

- `page` (integer): Page number, starting at `1`. Default `1`.

- `limit` (integer): Results per page, from `1` to `100`. Default `50`.

- `status` (string): Only results with this status: `pending`, `processing`, `completed`, `failed` or `canceled`.

- `result` (string): Only results with this outcome: `safe`, `invalid`, `disposable`, `disabled`, `inbox_full` or `unknown`. To find role-based addresses, use `result.exact=role`.

- `match`, `order`, `direction`: see [Filtering](https://emailit.com/docs/api-reference/filtering/).

## Filters and sort

Filter and sort keys: see [Filtering](https://emailit.com/docs/api-reference/filtering/).

## Returns

Returns `200 OK` with the results in `data`, plus `next_page_url` and `previous_page_url` (`null` at either end). Each result has the address's `id` (`ev_…`), `email`, `status`, `result`, `score`, `risk`, `mx_records`, `error_message` (set when the verification failed) and timestamps. `result`, `score` and `risk` mean the same as in [Verify an address](/docs/api-reference/email-verifications/verify/). For every check, [export the results](/docs/api-reference/email-verifications/lists/export/).

Returns `404` if the list doesn't exist in your workspace.

**Request** `GET /email-verification-lists/{id}/results`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const results = await emailit.emailVerificationLists.results('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a', { page: 1, limit: 10 });
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

results = client.email_verification_lists.results("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a", {"page": 1, "limit": 10})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$results = $emailit->emailVerificationLists()->results('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a', ['page' => 1, 'limit' => 10]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

results = client.email_verification_lists.results("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a", page: 1, limit: 10)
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

results, err := client.EmailVerificationLists.Results("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a", nil)
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let results = emailit.email_verification_lists.results("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a", None).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject results = emailit.emailVerificationLists().results("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var results = emailit.EmailVerificationLists.Results("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$results = Emailit::emailVerificationLists()->results('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a', ['page' => 1, 'limit' => 10]);
```

**cURL**

```bash
curl -X GET "https://api.emailit.com/v2/email-verification-lists/evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a/results?page=1&limit=10" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"
```

**200**

```json
{
  "data": [
    {
      "id": "ev_2xLeA1Pn6Rw3Ks8Vb0Ht5Mq2Fd9c",
      "email": "ada@example.com",
      "status": "completed",
      "result": "safe",
      "score": 100,
      "risk": "low",
      "mx_records": [
        { "priority": 10, "exchange": "mx1.example.com" }
      ],
      "error_message": null,
      "created_at": "2026-10-01T10:30:02.441000+00:00",
      "updated_at": "2026-10-01T10:30:09.876000+00:00"
    },
    {
      "id": "ev_2xLeA2Qm7Sx4Lt9Wc1Ju6Nr3Ge0d",
      "email": "info@acme-typo.example",
      "status": "completed",
      "result": "invalid",
      "score": 25,
      "risk": "high",
      "mx_records": [],
      "error_message": null,
      "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
}
```

**404**

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Email verification list not found"
}
```

---
Source: https://emailit.com/docs/api-reference/email-verifications/lists/results/

## Export results — GET /email-verification-lists/{id}/export

> Download the results of a completed email verification list as an Excel (XLSX) file with one row per address.

# 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.

`GET /email-verification-lists/:id/export`

## Path parameters

- `id` (string, required): List 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. |

**Request** `GET /email-verification-lists/{id}/export`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const exported = await emailit.emailVerificationLists.export('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

exported = client.email_verification_lists.export("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$exported = $emailit->emailVerificationLists()->export('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

exported = client.email_verification_lists.export("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

exported, err := client.EmailVerificationLists.Export("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a")
```

**Rust**

```rust
use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let exported = emailit.email_verification_lists.export("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a").await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

ApiResponse exported = emailit.emailVerificationLists().export("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var exported = emailit.EmailVerificationLists.Export("evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$exported = Emailit::emailVerificationLists()->export('evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a');
```

**cURL**

```bash
curl -X GET "https://api.emailit.com/v2/email-verification-lists/evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a/export" \
  -H "Authorization: Bearer your_api_key" \
  -o verification_results.xlsx
```

**200**

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="evl_2xLe7Hc2Vq9Nb4Wt1Ys6Kd3Rf8a.xlsx"

<binary XLSX data>
```

**400**

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Cannot export incomplete list. List must be completed first."
}
```

**404**

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Email verification list not found"
}
```

---
Source: https://emailit.com/docs/api-reference/email-verifications/lists/export/