Use cases
Clean an email list
In short
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.
On this page
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 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 -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"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"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 until it is ready.
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}`);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 -X POST https://api.rocketverifier.com/v1/verify/bulk/$JOB_ID/confirm \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"const confirmed = await rv.batch.confirm(upload.jobId);
console.log(confirmed.creditsCharged, confirmed.creditsRemaining);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.
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 signatureswebhook = rv.webhooks.create(
"https://example.com/hooks/rocketverifier",
events=["job.completed", "job.failed"],
)
print(webhook.secret) # store it to verify signaturesFor 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 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 "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.csvimport { writeFile } from "node:fs/promises";
const csv = await rv.batch.download(upload.jobId, { filter: "send_safe", includeOriginal: true });
await writeFile("send-safe.csv", csv);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 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.
- Lists in a CRM or email platform stay clean on a schedule with a native connector, 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 -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 covers every field.
Next steps#
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.
Updated 11 November 2026Suggest an edit