# Verify emails in bulk

Source: https://docs.rocketverifier.com/api/batch
Endpoint: `POST https://api.rocketverifier.com/v1/verify/bulk` (OAuth scope `verify:bulk`)

> Send up to 100,000 addresses in one JSON request to POST /v1/verify/bulk and get a job id back at once. Poll the progress endpoint or subscribe to the job.completed webhook, then download every result as CSV or JSON. Each unique address costs 1 credit, and unknown results are refunded when the job completes.

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/verify/bulk \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Idempotency-Key: 7c1e2f9a-4b3d-4e8a-9f61-2d5c8b0a1e47" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October signups",
    "emails": ["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"]
  }'
```

Node.js:

```js
import RocketVerifier from "@rocketverifier/sdk";

const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);

const job = await rv.batch.create({
  name: "October signups",
  emails: ["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"],
});
console.log(job.id, job.creditsToUse);

const done = await rv.batch.wait(job.id, { timeout: 30 * 60_000 });
const rows = await rv.batch.download(done.id, { filter: "send_safe", parse: true });
```

Python:

```python
import os
from rocketverifier import RocketVerifier

rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])

job = rv.batch.create(
    emails=["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"],
    name="October signups",
)
print(job.id, job.credits_to_use)

done = rv.batch.wait(job.id, timeout=30 * 60)
rows = rv.batch.download(done.id, filter="send_safe", parse=True)
```

Response 200:

```json
{
  "job_id": "q3Lw8vR2nK5tY1zA0bC9dE",
  "total_emails": 3,
  "estimated_time_seconds": 10,
  "credits_to_use": 3,
  "credits_remaining": 9997
}
```

A bulk job verifies a list asynchronously: you send the addresses, get a `job_id` straight away, and read the results when the job completes. RocketVerifier processes up to 100,000 emails per hour, with the same engine and the same results as [single verification](https://docs.rocketverifier.com/api/verify).

## Create a bulk job

Send a JSON body with the addresses. Authenticate with an API key, or with an OAuth token that has the `verify:bulk` scope.

- `Authorization` (string, required):

`Bearer <API key or access token>`. See [authentication](https://docs.rocketverifier.com/authentication).

- `Idempotency-Key` (string):

Any unique string, such as a UUID. Retrying with the same key within 24 hours returns the original job instead of creating and charging a second one.

**Body**

| Field | Type | Description |
| --- | --- | --- |
| `emails` | array of strings | The addresses to verify. At most 100,000 unique addresses after deduplication. Blank entries and duplicates are dropped and never charged. required |
| `name` | string | A label for the job, shown in the dashboard and returned on every job endpoint. |

The response confirms what was queued and charged.

| Field | Type | Description |
| --- | --- | --- |
| `job_id` | string | The job id. Use it with every `/jobs/{jobId}` endpoint. |
| `total_emails` | integer | Unique addresses queued after deduplication. |
| `estimated_time_seconds` | integer | Rough processing estimate. |
| `credits_to_use` | integer | Credits charged for the job (0 for sandbox keys). Unknown results are refunded at completion. |
| `credits_remaining` | integer | Balance after the charge. |

- **Deduplication:** addresses are compared case-insensitively, and Gmail addresses that differ only by dots or a `+tag` count once. `total_emails` is the unique count, and only unique addresses are charged.
- **Limit:** 100,000 unique addresses per job. Files up to 500,000 rows go through [file upload](https://docs.rocketverifier.com/api/bulk-upload).
- **Sandbox:** an `rv_test_` key accepts only `@sandbox.rocketverifier.com` addresses, runs the whole job and reports `credits_to_use: 0`.

## Track progress

`GET /v1/jobs/{jobId}/progress` is the cheap way to poll: it reads the job's counters, never the result rows, and adds the live rate and an ETA.

`GET /v1/jobs/{jobId}/progress`

cURL:

```bash
curl https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/progress \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
const p = await rv.batch.progress("q3Lw8vR2nK5tY1zA0bC9dE");
console.log(`${p.percent}% done, ETA ${p.etaSeconds}s`);
```

Python:

```python
p = rv.batch.progress("q3Lw8vR2nK5tY1zA0bC9dE")
print(f"{p.percent}% done, ETA {p.eta_seconds}s")
```

Response 200:

```json
{
  "job_id": "q3Lw8vR2nK5tY1zA0bC9dE",
  "status": "processing",
  "total": 10000,
  "processed": 6250,
  "remaining": 3750,
  "percent": 62.5,
  "counts": { "valid": 5100, "invalid": 610, "risky": 140, "catch_all": 260, "disposable": 70, "unknown": 70 },
  "counts_by_status": { "deliverable": 5100, "undeliverable": 680, "risky": 140, "unknown": 330 },
  "rate_per_minute": 1875.0,
  "rate_source": "recent",
  "eta_seconds": 120,
  "started_at": "2026-11-11T10:30:02Z",
  "completed_at": null,
  "updated_at": "2026-11-11T10:33:21Z"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `job_id` | string | required |
| `status` | enum | `ingesting` (an upload is being read), `awaiting_confirmation` (free preview ready, waiting for `/confirm`), `pending`, `processing`, `completed`, `failed`, `cancelled`. required; one of `ingesting`, `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed`, `cancelled` |
| `total` | integer | Unique addresses in the job. required |
| `processed` | integer | Addresses finished so far. required |
| `remaining` | integer | Addresses still to verify. required |
| `percent` | number | Progress from 0 to 100, rounded to 2 decimals. required |
| `counts` | object | Finished addresses per internal classification (valid, invalid, risky, catch_all, disposable, unknown). required |
| `counts_by_status` | object | The same counts grouped into statuses with the `2025-01-01` mapping, so catch-all addresses count as `unknown`. required |
| `counts_by_status.deliverable` | integer |  |
| `counts_by_status.undeliverable` | integer |  |
| `counts_by_status.risky` | integer |  |
| `counts_by_status.unknown` | integer |  |
| `rate_per_minute` | number or null | Addresses finished per minute. Null until known. |
| `rate_source` | enum or null | `recent` (about the last 5 minutes) or `average` (since the job started). one of `recent`, `average` |
| `eta_seconds` | integer or null | Estimated seconds to completion. 0 once completed, null until known. |
| `started_at` | string (date-time) or null |  |
| `completed_at` | string (date-time) or null |  |
| `updated_at` | string (date-time) or null |  |

## Wait for a job to finish

Subscribe a [webhook](https://docs.rocketverifier.com/api/webhooks) to `job.completed` and `job.failed` in production: you get a signed event with the final counters the moment the job ends, with no polling. For scripts, the SDKs' `wait` helpers poll the job every 5 seconds until it is `completed`, `failed` or `cancelled`. Their default timeout is 5 minutes, so raise it for large lists.

| Status | Meaning |
| --- | --- |
| `pending` | Charged and queued. |
| `processing` | Verification is running. |
| `completed` | Every address has a result. Unknown results are being refunded and webhooks fire. |
| `failed` | The job stopped. Credits for unprocessed addresses are refunded. |
| `cancelled` | You cancelled it. |
| `ingesting`, `awaiting_confirmation` | File uploads only. See [bulk upload](https://docs.rocketverifier.com/api/bulk-upload#follow-the-job-lifecycle). |

## Get job status

`GET /v1/jobs/{jobId}` returns the job's status and its counters by classification.

`GET /v1/jobs/{jobId}`

cURL:

```bash
curl https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The job id. |
| `name` | string or null | The job name you set. |
| `status` | enum | `ingesting` (an upload is being read), `awaiting_confirmation` (free preview ready, waiting for `/confirm`), `pending`, `processing`, `completed`, `failed`, `cancelled`. one of `ingesting`, `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed`, `cancelled` |
| `total_emails` | integer | Unique addresses in the job. |
| `processed_emails` | integer | Addresses finished so far. |
| `valid_count` | integer | Classified `valid` (deliverable). |
| `invalid_count` | integer | Classified `invalid` (undeliverable). |
| `risky_count` | integer | Classified `risky`. |
| `catch_all_count` | integer | On catch-all domains. Reported as `risky` with result version `2026-11-01`, `unknown` with `2025-01-01`. |
| `disposable_count` | integer | Disposable addresses (undeliverable). |
| `unknown_count` | integer | No conclusive answer. Refunded at completion. |
| `progress_percent` | number | Progress from 0 to 100. |
| `created_at` | string (date-time) |  |
| `started_at` | string (date-time) or null |  |
| `completed_at` | string (date-time) or null |  |

## List jobs

`GET /v1/jobs` lists your jobs, most recent first. Each item has the same fields as the job status plus `credits_used` and, once completed, `download_url`.

`GET /v1/jobs`

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer | Page number, starting at 1. min 1; default 1 |
| `limit` | integer | Jobs per page. 1 to 100; default 20 |
| `status` | enum | Only jobs in this status. one of `ingesting`, `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed`, `cancelled` |

cURL:

```bash
curl "https://api.rocketverifier.com/v1/jobs?status=completed&limit=50" \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
const page = await rv.batch.listPage({ status: "completed", limit: 50 });
console.log(page.total, page.hasMore);
```

Python:

```python
page = rv.batch.list_page(status="completed", limit=50)
print(page.total, page.has_more)
```

## Read results page by page

`GET /v1/jobs/{jobId}/results` returns per-address results in pages of up to 1,000. It works while the job is running, returning the rows finished so far.

`GET /v1/jobs/{jobId}/results`

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer | Page number, starting at 1. min 1; default 1 |
| `limit` | integer | Results per page. 1 to 1000; default 100 |
| `classification` | enum | Only rows with this internal classification. To filter by public status instead, use the `filter` parameter of the download endpoint. one of `valid`, `invalid`, `risky`, `catch_all`, `disposable`, `unknown` |

cURL:

```bash
curl "https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/results?limit=1000&page=1" \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
for await (const r of rv.batch.iterateResults("q3Lw8vR2nK5tY1zA0bC9dE")) {
  console.log(r.email, r.classification, r.subStatus);
}
```

Python:

```python
for r in rv.batch.iter_results("q3Lw8vR2nK5tY1zA0bC9dE"):
    print(r.email, r.classification, r.sub_status)
```

Response 200:

```json
{
  "job_id": "q3Lw8vR2nK5tY1zA0bC9dE",
  "status": "completed",
  "results": [
    {
      "email": "maya@northwind.io",
      "status": "deliverable",
      "classification": "valid",
      "is_valid": true,
      "is_disposable": false,
      "is_catch_all": false,
      "confidence_score": 97,
      "sub_status": "none",
      "verified_at": "2026-11-11T10:31:44Z"
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 1000,
  "has_more": false
}
```

| Field | Type | Description |
| --- | --- | --- |
| `email` | string | The address as submitted. |
| `status` | enum | The public status, mapped with the result version in effect. one of `deliverable`, `undeliverable`, `risky`, `unknown` |
| `classification` | enum | The internal classification behind `status`. one of `valid`, `invalid`, `risky`, `catch_all`, `disposable`, `unknown` |
| `is_valid` | boolean | True when `classification` is `valid`. |
| `is_disposable` | boolean |  |
| `is_catch_all` | boolean |  |
| `confidence_score` | integer | The 0 to 100 score. |
| `sub_status` | enum | The precise reason behind the result. Same values as `sub_status` on `/verify`. one of `none`, `alias`, `forwarder`, `mailbox_not_found`, `account_disabled`, `does_not_accept_mail`, `invalid_syntax`, `invalid_domain`, `disposable`, `catch_all`, `role_based`, `mailbox_full`, `possible_trap`, `toxic`, `do_not_mail`, `accepts_then_bounces`, `privacy_relay`, `parked_domain`, `possible_typo`, `dns_error`, `greylisted`, `blocked`, `smtp_timeout`, `no_connect`, `smtp_unavailable` |
| `verified_at` | string (date-time) or null |  |

`status` follows the [result version](https://docs.rocketverifier.com/versioning) in effect, so send the `RocketVerifier-Version` header here too if you set it on single verifications.

## Download results

`GET /v1/jobs/{jobId}/download` streams every result of a completed job in one response, with no row cap. It is the fastest way to export a job, and it can filter rows and keep your own columns.

`GET /v1/jobs/{jobId}/download`

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `format` | enum | File format. Ignored when `columns` is set (always CSV). default "csv"; one of `csv`, `json` |
| `filter` | enum | Only rows with this public status, mapped with the result version in effect. `send_safe` keeps deliverable addresses that are not disposable or role addresses, plus catch-all addresses with a score of 65 or more. one of `deliverable`, `undeliverable`, `risky`, `unknown`, `send_safe` |
| `include_original` | boolean | Start each row with the uploaded file's own columns, then the results as `rv_` columns. Jobs from a connector sync get the email, platform contact id, first and last name and a link to the contact. Ignored when `columns` is set. default false |
| `columns` | enum | CSV in another provider's column layout, with the closest equivalent values, so spreadsheets and import rules built for that provider keep working. one of `zerobounce`, `bouncer`, `kickbox` |

cURL:

```bash
curl -o send-safe.csv \
  "https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/download?filter=send_safe" \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
// Raw CSV text, typed rows, or parsed JSON
const csv = await rv.batch.download("q3Lw8vR2nK5tY1zA0bC9dE");
const rows = await rv.batch.download("q3Lw8vR2nK5tY1zA0bC9dE", { filter: "send_safe", parse: true });
const json = await rv.batch.download("q3Lw8vR2nK5tY1zA0bC9dE", { format: "json" });
```

Python:

```python
csv_text = rv.batch.download("q3Lw8vR2nK5tY1zA0bC9dE")
rows = rv.batch.download("q3Lw8vR2nK5tY1zA0bC9dE", filter="send_safe", parse=True)
data = rv.batch.download("q3Lw8vR2nK5tY1zA0bC9dE", format="json")
```

### Read the CSV columns

The default CSV has these columns, in this order. New columns are only ever appended, so positional readers keep working.

CSV header:

```text
email,classification,is_valid,is_disposable,is_catch_all,is_role_based,confidence_score,sub_status,verified_at,did_you_mean,catch_all_verdict,catch_all_score,free,toxic,spam_trap,disabled,mailbox_full,smtp_provider,mx_record
```

With `format=json`, the body is `{"job_id": "...", "results": [...]}` and every row also has `status` (the public status). With `include_original=true`, each CSV row starts with your uploaded file's own columns, followed by `rv_status`, `rv_sub_status`, `rv_classification`, `rv_score`, `rv_is_disposable`, `rv_is_catch_all`, `rv_is_role_based`, `rv_suggestion`, `rv_verified_at` and the `rv_` detail columns. JSON rows get an `original` object instead.

| Field | Type | Description |
| --- | --- | --- |
| `email` | string |  |
| `status` | enum | The public status (JSON only). one of `deliverable`, `undeliverable`, `risky`, `unknown` |
| `classification` | enum | one of `valid`, `invalid`, `risky`, `catch_all`, `disposable`, `unknown` |
| `is_valid` | boolean |  |
| `is_disposable` | boolean |  |
| `is_catch_all` | boolean |  |
| `is_role_based` | boolean |  |
| `confidence_score` | integer |  |
| `sub_status` | string |  |
| `verified_at` | string or null |  |
| `did_you_mean` | string | Suggested correction, or an empty string. |
| `catch_all_verdict` | string | `send_safe`, `send_with_caution`, `avoid`, or an empty string. |
| `catch_all_score` | integer or null | Catch-all plausibility score, when the domain is catch-all. |
| `free` | boolean | Free mailbox provider. |
| `toxic` | boolean |  |
| `spam_trap` | boolean |  |
| `disabled` | boolean | Mailbox disabled. |
| `mailbox_full` | boolean |  |
| `smtp_provider` | string | Mail system behind the MX, or an empty string. |
| `mx_record` | string | Highest priority MX host, or an empty string. |
| `original` | object or null | With `include_original=true`, the uploaded row's own columns. |

### Filter rows by outcome

`filter` keeps only rows with one outcome. The four statuses follow the result version in effect, so catch-all addresses land in `risky` with `2026-11-01` and in `unknown` with `2025-01-01`.

| `filter` | Rows kept |
| --- | --- |
| `deliverable` | Classification `valid`. |
| `undeliverable` | `invalid` and `disposable`. |
| `risky` | `risky`, plus `catch_all` with result version `2026-11-01`. |
| `unknown` | `unknown`, plus `catch_all` with result version `2025-01-01`. |
| `send_safe` | `valid` addresses that are not disposable or role addresses, plus catch-all addresses with a score of 65 or more. The ready-to-send list. |

### Use another provider's column layout

`columns` writes the CSV in another provider's layout, with the closest equivalent values, so spreadsheets and import rules built for that tool keep working the day you switch. It always returns CSV, works with `filter`, and ignores `format` and `include_original`.

| `columns` | Header |
| --- | --- |
| `zerobounce` | `Email Address`, `ZB Status`, `ZB Sub status`, `ZB Free Email`, `ZB Did You Mean`, `ZB MX Found`, `ZB MX Record`, `ZB SMTP Provider` |
| `bouncer` | `email`, `status`, `reason`, `domain_accept_all`, `domain_disposable`, `domain_free`, `account_role`, `account_disabled`, `account_full_mailbox`, `score`, `provider`, `did_you_mean` |
| `kickbox` | `email`, `result`, `reason`, `role`, `free`, `disposable`, `accept_all`, `did_you_mean`, `sendex` |

cURL:

```bash
curl -o results.csv \
  "https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/download?columns=kickbox" \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

In the `kickbox` layout, `sendex` is the RocketVerifier score divided by 100.

## Cancel a job

`DELETE /v1/jobs/{jobId}` stops a job and refunds every address that was not processed yet, immediately. It needs the `jobs:write` scope.

`DELETE /v1/jobs/{jobId}`

cURL:

```bash
curl -X DELETE https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
const { refundedCredits } = await rv.batch.cancel("q3Lw8vR2nK5tY1zA0bC9dE");
```

Python:

```python
result = rv.batch.cancel("q3Lw8vR2nK5tY1zA0bC9dE")
print(result.refunded_credits)
```

Response 200:

```json
{
  "success": true,
  "job_id": "q3Lw8vR2nK5tY1zA0bC9dE",
  "refunded_credits": 500,
  "message": "Job cancelled; 500 credits refunded"
}
```

Jobs that are `pending`, `processing`, `ingesting` or `awaiting_confirmation` can be cancelled. Uploads that were never charged refund nothing because nothing was spent. A job that already ended returns `400 job_not_cancellable`.

## Credits

- **Charged at creation:** 1 credit per unique address. Duplicates are never charged.
- **Refunded at completion:** every `unknown` result and every address on your own suppression list, automatically.
- **Refunded on cancel or failure:** every address that was not processed.
- **Free:** jobs run with an `rv_test_` sandbox key.
- **Bounce guarantee:** hard bounces on addresses a job marked deliverable come back as credits. See the [bounce guarantee](https://docs.rocketverifier.com/integrations/bounce-guarantee).

A `credits.low` or `credits.depleted` [webhook](https://docs.rocketverifier.com/api/webhooks#creditslow-and-creditsdepleted) tells you when a job leaves the balance low.

## Errors

| Status | `error.code` | When it happens |
| --- | --- | --- |
| 400 | `no_emails` | The list is empty after removing blank entries. |
| 400 | `too_many_emails` | More than 100,000 unique addresses. `details.max` and `details.provided` say by how much. |
| 400 | `job_not_complete` | You asked to download a job that has not completed. |
| 400 | `job_not_cancellable` | The job already completed, failed or was cancelled. |
| 401 | `unauthorized`, `api_key_expired` | The key is missing, invalid, revoked or expired. |
| 402 | `insufficient_credits` | The balance does not cover the unique addresses. `details.required` and `details.available` say by how much. |
| 402 | `api_key_spend_cap_reached` | The job would pass this key's monthly spend cap. |
| 403 | `insufficient_credits` | The balance is zero. |
| 403 | `sandbox_key_restricted` | An `rv_test_` key was sent real addresses. |
| 403 | `insufficient_scope` | The credential lacks `verify:bulk`, `jobs:read` or `jobs:write`. |
| 404 | `not_found` | No job with this id on your account. |
| 409 | `job_not_cancellable` | The job finished while the cancel was running. |
| 422 | `validation_error` | The body is not valid JSON, `emails` is missing, or a query parameter has an unknown value. |
| 429 | `rate_limited` | Too many requests. Wait for the `Retry-After` seconds. |
| 503 | `maintenance` | Bulk intake is paused briefly. Retry after the `Retry-After` seconds. |

Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors).

## Frequently asked questions

### How many addresses can one job hold?

100,000 unique addresses per JSON request. Duplicates are removed first and never count. For larger lists, upload a file with POST /v1/verify/bulk/upload, which takes up to 500,000 unique addresses.

### When am I charged for a bulk job?

When the job is created, 1 credit per unique address. When it completes, every unknown result and every address on your suppression list is refunded automatically. Cancelling refunds every address that was not processed yet.

### How fast does a job finish?

RocketVerifier processes up to 100,000 emails per hour. The progress endpoint reports the live rate and an ETA in seconds.

### Should I poll or use a webhook?

Use the job.completed webhook in production, so you hear about the job the moment it finishes. Poll GET /v1/jobs/{jobId}/progress for progress bars and scripts. It reads counters only and is cheap to call.

### Can I test bulk jobs for free?

Yes. With an rv_test_ sandbox key, a job of @sandbox.rocketverifier.com addresses runs end to end and charges nothing.
