Skip to content
RocketVerifierDOCS
POSThttps://api.rocketverifier.com/v1/verify/bulk

Verify 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"]
  }'
Response 200
{
  "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

  • emailsarray of stringsrequired

    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.

  • 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.
  • 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 https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/progress \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
Response 200
{
  "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"
}
  • job_idstringrequired
  • statusenumrequired

    ingesting (an upload is being read), awaiting_confirmation (free preview ready, waiting for /confirm), pending, processing, completed, failed, cancelled.

    ingestingawaiting_confirmationpendingprocessingcompletedfailedcancelled
  • totalintegerrequired

    Unique addresses in the job.

  • processedintegerrequired

    Addresses finished so far.

  • remainingintegerrequired

    Addresses still to verify.

  • percentnumberrequired

    Progress from 0 to 100, rounded to 2 decimals.

  • countsobjectrequired

    Finished addresses per internal classification (valid, invalid, risky, catch_all, disposable, unknown).

  • counts_by_statusobjectrequired

    The same counts grouped into statuses with the 2025-01-01 mapping, so catch-all addresses count as unknown.

    › Show 4 child fields
  • rate_per_minutenumber or null

    Addresses finished per minute. Null until known.

  • rate_sourceenum or null

    recent (about the last 5 minutes) or average (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.

StatusMeaning
pendingCharged and queued.
processingVerification is running.
completedEvery address has a result. Unknown results are being refunded and webhooks fire.
failedThe job stopped. Credits for unprocessed addresses are refunded.
cancelledYou cancelled it.
ingesting, awaiting_confirmationFile uploads only. See bulk upload.

Get job status#

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

GET/v1/jobs/{jobId}
cURL
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
  • Unique addresses in the job.

  • Addresses finished so far.

  • Classified valid (deliverable).

  • Classified invalid (undeliverable).

  • Classified risky.

  • On catch-all domains. Reported as risky with result version 2026-11-01, unknown with 2025-01-01.

  • Disposable addresses (undeliverable).

  • No conclusive answer. Refunded at completion.

  • 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.

GET/v1/jobs

Query parameters

  • pageintegermin 1default 1

    Page number, starting at 1.

  • limitinteger1 to 100default 20

    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"

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

  • pageintegermin 1default 1

    Page number, starting at 1.

  • limitinteger1 to 1000default 100

    Results per page.

  • Only rows with this internal classification. To filter by public status instead, use the filter parameter 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"
Response 200
{
  "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
  • The internal classification behind status.

    validinvalidriskycatch_alldisposableunknown
  • is_validboolean

    True when classification is valid.

  • The 0 to 100 score.

  • The precise reason behind the result. Same values as sub_status on /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.

GET/v1/jobs/{jobId}/download

Query parameters

  • formatenumdefault "csv"

    File format. Ignored when columns is set (always CSV).

    csvjson
  • filterenum

    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.

    deliverableundeliverableriskyunknownsend_safe
  • include_originalbooleandefault false

    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.

  • 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"

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

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.

filterRows kept
deliverableClassification valid.
undeliverableinvalid and disposable.
riskyrisky, plus catch_all with result version 2026-11-01.
unknownunknown, plus catch_all with result version 2025-01-01.
send_safevalid 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.

columnsHeader
zerobounceEmail Address, ZB Status, ZB Sub status, ZB Free Email, ZB Did You Mean, ZB MX Found, ZB MX Record, ZB SMTP Provider
bounceremail, status, reason, domain_accept_all, domain_disposable, domain_free, account_role, account_disabled, account_full_mailbox, score, provider, did_you_mean
kickboxemail, result, reason, role, free, disposable, accept_all, did_you_mean, sendex
cURL
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.

DEL/v1/jobs/{jobId}
curl -X DELETE https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
Response 200
{
  "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.

A credits.low or credits.depleted webhook tells you when a job leaves the balance low.

Errors#

Statuserror.codeWhen it happens
400no_emailsThe list is empty after removing blank entries.
400too_many_emailsMore than 100,000 unique addresses. details.max and details.provided say by how much.
400job_not_completeYou asked to download a job that has not completed.
400job_not_cancellableThe job already completed, failed or was cancelled.
401unauthorized, api_key_expiredThe key is missing, invalid, revoked or expired.
402insufficient_creditsThe balance does not cover the unique addresses. details.required and details.available say by how much.
402api_key_spend_cap_reachedThe job would pass this key's monthly spend cap.
403insufficient_creditsThe balance is zero.
403sandbox_key_restrictedAn rv_test_ key was sent real addresses.
403insufficient_scopeThe credential lacks verify:bulk, jobs:read or jobs:write.
404not_foundNo job with this id on your account.
409job_not_cancellableThe job finished while the cancel was running.
422validation_errorThe body is not valid JSON, emails is missing, or a query parameter has an unknown value.
429rate_limitedToo many requests. Wait for the Retry-After seconds.
503maintenanceBulk 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