https://api.rocketverifier.com/v1/verify/bulkVerify emails in bulk
In short
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.
OAuth scope verify:bulk
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"]
}'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 });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){
"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.
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.
Headers
- Authorizationstringrequired
Bearer <API key or access token>. See authentication. - Idempotency-Keystring
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
The addresses to verify. At most 100,000 unique addresses after deduplication. Blank entries and duplicates are dropped and never charged.
- namestring
A label for the job, shown in the dashboard and returned on every job endpoint.
The response confirms what was queued and charged.
- job_idstring
The job id. Use it with every
/jobs/{jobId}endpoint. - total_emailsinteger
Unique addresses queued after deduplication.
- estimated_time_secondsinteger
Rough processing estimate.
- credits_to_useinteger
Credits charged for the job (0 for sandbox keys). Unknown results are refunded at completion.
- credits_remaininginteger
Balance after the charge.
- Deduplication: addresses are compared case-insensitively, and Gmail addresses that differ only by dots or a
+tagcount once.total_emailsis 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.
- Sandbox: an
rv_test_key accepts only@sandbox.rocketverifier.comaddresses, runs the whole job and reportscredits_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.
/v1/jobs/{jobId}/progresscurl https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/progress \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"const p = await rv.batch.progress("q3Lw8vR2nK5tY1zA0bC9dE");
console.log(`${p.percent}% done, ETA ${p.etaSeconds}s`);p = rv.batch.progress("q3Lw8vR2nK5tY1zA0bC9dE")
print(f"{p.percent}% done, ETA {p.eta_seconds}s"){
"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"
}ingesting(an upload is being read),awaiting_confirmation(free preview ready, waiting for/confirm),pending,processing,completed,failed,cancelled.ingestingawaiting_confirmationpendingprocessingcompletedfailedcancelledUnique addresses in the job.
Addresses finished so far.
Addresses still to verify.
Progress from 0 to 100, rounded to 2 decimals.
Finished addresses per internal classification (valid, invalid, risky, catch_all, disposable, unknown).
The same counts grouped into statuses with the
2025-01-01mapping, so catch-all addresses count asunknown.› Show 4 child fields
- deliverableinteger
- undeliverableinteger
- riskyinteger
- unknowninteger
- rate_per_minutenumber or null
Addresses finished per minute. Null until known.
- rate_sourceenum or null
recent(about the last 5 minutes) oraverage(since the job started).recentaverage - eta_secondsinteger or null
Estimated seconds to completion. 0 once completed, null until known.
- started_atstring (date-time) or null
- completed_atstring (date-time) or null
- updated_atstring (date-time) or null
Wait for a job to finish#
Subscribe a webhook 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. |
Get job status#
GET /v1/jobs/{jobId} returns the job's status and its counters by classification.
/v1/jobs/{jobId}curl https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"- idstring
The job id.
- namestring or null
The job name you set.
- statusenum
ingesting(an upload is being read),awaiting_confirmation(free preview ready, waiting for/confirm),pending,processing,completed,failed,cancelled.ingestingawaiting_confirmationpendingprocessingcompletedfailedcancelled - total_emailsinteger
Unique addresses in the job.
- processed_emailsinteger
Addresses finished so far.
- valid_countinteger
Classified
valid(deliverable). - invalid_countinteger
Classified
invalid(undeliverable). - risky_countinteger
Classified
risky. - catch_all_countinteger
On catch-all domains. Reported as
riskywith result version2026-11-01,unknownwith2025-01-01. - disposable_countinteger
Disposable addresses (undeliverable).
- unknown_countinteger
No conclusive answer. Refunded at completion.
- progress_percentnumber
Progress from 0 to 100.
- created_atstring (date-time)
- started_atstring (date-time) or null
- completed_atstring (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.
/v1/jobsQuery parameters
Page number, starting at 1.
Jobs per page.
- statusenum
Only jobs in this status.
ingestingawaiting_confirmationpendingprocessingcompletedfailedcancelled
curl "https://api.rocketverifier.com/v1/jobs?status=completed&limit=50" \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"const page = await rv.batch.listPage({ status: "completed", limit: 50 });
console.log(page.total, page.hasMore);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.
/v1/jobs/{jobId}/resultsQuery parameters
Page number, starting at 1.
Results per page.
- classificationenum
Only rows with this internal classification. To filter by public status instead, use the
filterparameter of the download endpoint.validinvalidriskycatch_alldisposableunknown
curl "https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/results?limit=1000&page=1" \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"for await (const r of rv.batch.iterateResults("q3Lw8vR2nK5tY1zA0bC9dE")) {
console.log(r.email, r.classification, r.subStatus);
}for r in rv.batch.iter_results("q3Lw8vR2nK5tY1zA0bC9dE"):
print(r.email, r.classification, r.sub_status){
"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
}- emailstring
The address as submitted.
- statusenum
The public status, mapped with the result version in effect.
deliverableundeliverableriskyunknown - classificationenum
The internal classification behind
status.validinvalidriskycatch_alldisposableunknown - is_validboolean
True when
classificationisvalid. - is_disposableboolean
- is_catch_allboolean
- confidence_scoreinteger
The 0 to 100 score.
- sub_statusenum
The precise reason behind the result. Same values as
sub_statuson/verify.nonealiasforwardermailbox_not_foundaccount_disableddoes_not_accept_mailinvalid_syntaxinvalid_domaindisposablecatch_allrole_basedmailbox_fullpossible_traptoxicdo_not_mailaccepts_then_bouncesprivacy_relayparked_domainpossible_typodns_errorgreylistedblockedsmtp_timeoutno_connectsmtp_unavailable - verified_atstring (date-time) or null
status follows the result version 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.
/v1/jobs/{jobId}/downloadQuery parameters
File format. Ignored when
columnsis set (always CSV).csvjson- filterenum
Only rows with this public status, mapped with the result version in effect.
send_safekeeps deliverable addresses that are not disposable or role addresses, plus catch-all addresses with a score of 65 or more.deliverableundeliverableriskyunknownsend_safe 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 whencolumnsis set.- columnsenum
CSV in another provider's column layout, with the closest equivalent values, so spreadsheets and import rules built for that provider keep working.
zerobouncebouncerkickbox
curl -o send-safe.csv \
"https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/download?filter=send_safe" \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"// 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" });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.
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_recordWith 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.
- emailstring
- statusenum
The public status (JSON only).
deliverableundeliverableriskyunknown - classificationenumvalidinvalidriskycatch_alldisposableunknown
- is_validboolean
- is_disposableboolean
- is_catch_allboolean
- is_role_basedboolean
- confidence_scoreinteger
- sub_statusstring
- verified_atstring or null
- did_you_meanstring
Suggested correction, or an empty string.
- catch_all_verdictstring
send_safe,send_with_caution,avoid, or an empty string. - catch_all_scoreinteger or null
Catch-all plausibility score, when the domain is catch-all.
- freeboolean
Free mailbox provider.
- toxicboolean
- spam_trapboolean
- disabledboolean
Mailbox disabled.
- mailbox_fullboolean
- smtp_providerstring
Mail system behind the MX, or an empty string.
- mx_recordstring
Highest priority MX host, or an empty string.
- originalobject 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 -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.
/v1/jobs/{jobId}curl -X DELETE https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"const { refundedCredits } = await rv.batch.cancel("q3Lw8vR2nK5tY1zA0bC9dE");result = rv.batch.cancel("q3Lw8vR2nK5tY1zA0bC9dE")
print(result.refunded_credits){
"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
unknownresult 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.
A credits.low or credits.depleted webhook 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.
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.
Updated 11 November 2026Suggest an edit