# Clean an email list

Source: https://docs.rocketverifier.com/guides/list-cleaning

> Upload the file with preview=true and read the free list health preview, which estimates the bounce rate and the credits needed before you spend anything. Confirm to verify every unique address for 1 credit each, get a job.completed webhook, then download the send_safe, risky and unknown segments. Re-verify anything older than 30 days before you mail it, and let a monitor watch the list in between.

A list cleaning run has five steps: upload, preview, confirm, wait, download. The free preview comes first, so you know the list's health and the cost before a single credit is spent.

## Upload the file

Send the file to [`POST /v1/verify/bulk/upload`](https://docs.rocketverifier.com/api/bulk-upload) with `preview=true`. The API accepts CSV, TSV, TXT and XLSX files up to 50 MB and 500,000 unique addresses, or a public HTTPS `source_url` it fetches for you.

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/verify/bulk/upload \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -F "file=@contacts.csv" \
  -F "name=Q4 newsletter list" \
  -F "email_column=Work Email" \
  -F "preview=true"
```

Node.js:

```js
import { readFile } from "node:fs/promises";
import RocketVerifier from "@rocketverifier/sdk";

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

const upload = await rv.batch.upload({
  file: await readFile("contacts.csv"),
  filename: "contacts.csv",
  name: "Q4 newsletter list",
  emailColumn: "Work Email",
  preview: true,
});
console.log(upload.jobId, upload.status); // "ingesting"
```

Python:

```python
import os
from rocketverifier import RocketVerifier

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

upload = rv.batch.upload(
    "contacts.csv",
    name="Q4 newsletter list",
    email_column="Work Email",
    preview=True,
)
print(upload.job_id, upload.status)  # "ingesting"
```

The email column is found automatically when you leave out `email_column`. Every other column is kept, so the download can return your original data next to the results. Prefer the dashboard? **Bulk verify** runs the same flow with a drag and drop upload.

## Read the free preview

The preview runs on every row and costs nothing: syntax, disposable domains, role addresses, MX records, duplicates and your suppression lists, plus a live mailbox check on a random sample (2% of the list, at most 200 addresses). Poll [`POST /v1/verify/bulk/{id}/preview`](https://docs.rocketverifier.com/api/bulk-upload) until it is ready.

Node.js:

```js
let result = await rv.batch.preview(upload.jobId);
while (result.pending) {
  await new Promise((r) => setTimeout(r, 3000));
  result = await rv.batch.preview(upload.jobId);
}

const p = result.preview;
console.log(`Estimated bounce rate: ${(p.estimatedBounceRate * 100).toFixed(1)}%`);
console.log(`Credits on confirm: ${p.creditsNeeded}, after unknown refunds: ${p.estimatedCreditsAfterRefunds}`);
```

Python:

```python
import time

result = rv.batch.preview(upload.job_id)
while result.pending:
    time.sleep(3)
    result = rv.batch.preview(upload.job_id)

p = result.preview
print(f"Estimated bounce rate: {p.estimated_bounce_rate:.1%}")
print(f"Credits on confirm: {p.credits_needed}, after unknown refunds: {p.estimated_credits_after_refunds}")
```

| Preview field | Meaning |
| --- | --- |
| `estimated_bounce_rate` | Share of the list (0 to 1) expected to hard-bounce if you mailed it today |
| `risky_share`, `unknown_share` | Expected share of risky and unknown results |
| `credits_needed` | Credits charged on confirm: 1 per unique address |
| `estimated_credits_after_refunds` | Expected net cost once unknown results are refunded |
| `free_checks` | Counts from the per-row checks, such as invalid syntax, no MX, disposable and role addresses |
| `confidence` | `high`, `medium` or `low`, from the sample size |

A list with a high estimated bounce rate is exactly the list to verify before you send. A list that comes back clean and recently verified can wait.

## Confirm the job

Confirming charges 1 credit per unique address and starts verification. It is safe to retry: a job is never charged twice.

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/verify/bulk/$JOB_ID/confirm \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
const confirmed = await rv.batch.confirm(upload.jobId);
console.log(confirmed.creditsCharged, confirmed.creditsRemaining);
```

Python:

```python
confirmed = rv.batch.confirm(upload.job_id)
print(confirmed.credits_charged, confirmed.credits_remaining)
```

Unknown results are refunded when the job completes, so the final cost is usually lower than the amount charged on confirm. Uploads without `preview=true` are charged and started as soon as the file is read.

## Get notified when it finishes

Register a webhook once, and every finished job sends a signed `job.completed` event with the counts and a `download_url`. Bulk jobs run at up to 100,000 emails per hour.

Node.js:

```js
const webhook = await rv.webhooks.create({
  url: "https://example.com/hooks/rocketverifier",
  events: ["job.completed", "job.failed"],
});
console.log(webhook.secret); // store it to verify signatures
```

Python:

```python
webhook = rv.webhooks.create(
    "https://example.com/hooks/rocketverifier",
    events=["job.completed", "job.failed"],
)
print(webhook.secret)  # store it to verify signatures
```

For a single job, pass `callback_url` with the upload instead. Scripts and notebooks can wait in place with `rv.batch.wait(jobId)` (Node.js) or `rv.batch.wait(job_id)` (Python), which polls every 5 seconds; raise its timeout for large lists. [Webhooks](https://docs.rocketverifier.com/api/webhooks) covers payloads and signature checks.

## Download the segments

Download the results as CSV or JSON, all at once or one segment at a time with `filter`:

| `filter` | Rows |
| --- | --- |
| `send_safe` | Every deliverable address plus catch-all addresses scoring 65 or more, without disposable or role addresses |
| `deliverable` | Mailbox confirmed |
| `risky` | Accepts mail with a named risk; includes catch-all under result version `2026-11-01` |
| `undeliverable` | Will bounce |
| `unknown` | No conclusive answer, refunded |

cURL:

```bash
curl "https://api.rocketverifier.com/v1/jobs/$JOB_ID/download?filter=send_safe&include_original=true" \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "RocketVerifier-Version: 2026-11-01" \
  -o send-safe.csv
```

Node.js:

```js
import { writeFile } from "node:fs/promises";

const csv = await rv.batch.download(upload.jobId, { filter: "send_safe", includeOriginal: true });
await writeFile("send-safe.csv", csv);
```

Python:

```python
csv = rv.batch.download(upload.job_id, filter="send_safe", include_original=True)
with open("send-safe.csv", "w") as f:
    f.write(csv)
```

`include_original=true` puts your uploaded columns first, so the file drops straight back into your email platform. Each row also carries `sub_status`, `did_you_mean`, `catch_all_verdict`, `catch_all_score` and the other detail columns.

## Decide what to keep

Keep what will deliver, remove what will bounce or harm your reputation, and hold the rest for another look.

| Segment | Action |
| --- | --- |
| `deliverable` | Keep |
| `risky` + `catch_all`, verdict `send_safe` | Keep |
| `risky` + `catch_all`, verdict `send_with_caution` | Send to engaged contacts first, watch bounces |
| `risky` + `role_based` | Keep for B2B and transactional mail |
| `risky` + `mailbox_full` | Suppress for now, re-verify in a later run |
| `risky` + `possible_trap`, `toxic`, `do_not_mail`, `accepts_then_bounces`, `parked_domain` | Remove |
| `risky` + `catch_all`, verdict `avoid` | Remove |
| `undeliverable` (including `disposable`) | Remove. Fix `did_you_mean` typos only when the contact confirms them. |
| `unknown` | Hold, and re-verify in a new job after a few hours |

Mail the kept addresses through a connected SendGrid, Mailgun or Postmark account and the [Bounce Guarantee](https://docs.rocketverifier.com/integrations/bounce-guarantee) refunds every hard bounce on a deliverable result automatically.

## Keep the list fresh

Mailboxes close and domains lapse, so a clean list does not stay clean. Build verification into the list's lifecycle:

- **Before each campaign,** re-verify every address whose last check is older than 30 days. The native connectors use the same 30 day window by default and skip contacts verified more recently.
- **Unknown results** go into a new job after their `retry_after`. They cost nothing until they return a real answer.
- **New contacts** are best verified at the point of capture. See [verify at signup](https://docs.rocketverifier.com/guides/signup-verification).
- **Lists in a CRM or email platform** stay clean on a schedule with a [native connector](https://docs.rocketverifier.com/guides/crm-hygiene), which writes the results back to each contact.

### Watch a list with a monitor

A list health monitor re-verifies a saved list of up to 5,000 addresses daily or weekly and alerts you when the share of invalid and risky addresses passes your threshold. Each run is charged like a bulk job, 1 credit per unique address with unknown results refunded. A domain authentication monitor watches your sending domain's SPF, DKIM, DMARC and blocklist status for free.

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/monitors \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP customers",
    "type": "list_health",
    "frequency": "weekly",
    "alert_threshold": 5,
    "emails": ["maya@northwind.io", "li.wei@lakeside-dental.com"]
  }'
```

Alerts arrive as a `monitor.alert` webhook. The [monitors reference](https://docs.rocketverifier.com/api/monitors) covers every field.

## Next steps

- [Bulk upload reference](https://docs.rocketverifier.com/api/bulk-upload)
Every upload, preview and confirm field.
- [Reading results](https://docs.rocketverifier.com/results)
What every status and sub_status means and costs.
- [Keep a CRM clean](https://docs.rocketverifier.com/guides/crm-hygiene)
Scheduled syncs that write results back to each contact.
- [Webhooks](https://docs.rocketverifier.com/api/webhooks)
Signed events for finished jobs and monitor alerts.

## Frequently asked questions

### How big can a list be?

A file upload takes up to 500,000 unique addresses and 50 MB, as CSV, TSV, TXT or XLSX. The JSON bulk endpoint takes up to 100,000 addresses per request.

### Am I charged for duplicates?

No. Addresses are deduplicated case-insensitively before charging, and each unique address costs 1 credit. Unknown results are refunded when the job completes.

### Is the preview really free?

Yes. The preview runs syntax, disposable, role, MX, duplicate and suppression checks on every row, plus a live mailbox check on a random sample, and charges nothing. You decide whether to verify after reading it.

### How long does a job take?

Bulk verification runs at up to 100,000 emails per hour. Register a job.completed webhook instead of waiting on the request.

### Can I get the results in the same columns as my old verifier?

Yes. Add columns=zerobounce, bouncer or kickbox to the download to get a CSV in that tool's column layout, with the closest equivalent values, so existing imports keep working.
