Skip to content
RocketVerifierDOCS

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"

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}`);
Preview fieldMeaning
estimated_bounce_rateShare of the list (0 to 1) expected to hard-bounce if you mailed it today
risky_share, unknown_shareExpected share of risky and unknown results
credits_neededCredits charged on confirm: 1 per unique address
estimated_credits_after_refundsExpected net cost once unknown results are refunded
free_checksCounts from the per-row checks, such as invalid syntax, no MX, disposable and role addresses
confidencehigh, 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"

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 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 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:

filterRows
send_safeEvery deliverable address plus catch-all addresses scoring 65 or more, without disposable or role addresses
deliverableMailbox confirmed
riskyAccepts mail with a named risk; includes catch-all under result version 2026-11-01
undeliverableWill bounce
unknownNo 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.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.

SegmentAction
deliverableKeep
risky + catch_all, verdict send_safeKeep
risky + catch_all, verdict send_with_cautionSend to engaged contacts first, watch bounces
risky + role_basedKeep for B2B and transactional mail
risky + mailbox_fullSuppress for now, re-verify in a later run
risky + possible_trap, toxic, do_not_mail, accepts_then_bounces, parked_domainRemove
risky + catch_all, verdict avoidRemove
undeliverable (including disposable)Remove. Fix did_you_mean typos only when the contact confirms them.
unknownHold, 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
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