Skip to content
RocketVerifierDOCS

Libraries

SDKs and CLI

In short

RocketVerifier ships official SDKs for Node.js, Python, Go, PHP and Ruby and a command line tool. Every SDK handles authentication, safe retries with an Idempotency-Key, typed results with yes and no flags as booleans, bulk jobs and uploads, webhook signatures, monitors and OAuth.

On this page

Every official library wraps the full public API and is maintained by the RocketVerifier team. Choose the one for your language; they share the same concepts, method names follow each language's conventions, and every sample in these docs uses them.

Install a library#

Install the package for your language. Each SDK page has the full reference.

npm install @rocketverifier/sdk
LibraryPackageVersionRequiresRuntime dependencies
Node.js@rocketverifier/sdk2.2.1Node.js 18+None
Pythonrocketverifier1.4.0Python 3.8+requests, plus httpx for async
Gogithub.com/rocketverifier/sdk-go1.0.0Go 1.21+None
PHProcketverifier/sdk1.0.0PHP 8.1+ with curlNone
Rubyrocketverifier1.0.0Ruby 2.6+None
CLI@rocketverifier/cli1.1.0Node.js 18+commander

Verify your first email#

Create a client with your API key and verify an address. Sandbox addresses return fixed results and cost nothing, so this runs safely in tests.

import RocketVerifier from "@rocketverifier/sdk";

const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);
const result = await rv.verify("deliverable@sandbox.rocketverifier.com");
console.log(result.status, result.subStatus, result.domain.disposable);

What every SDK handles#

The five libraries implement the same behaviour, so moving between languages changes the syntax and nothing else.

  • Authentication: pass an API key (rv_live_ or rv_test_) or an OAuth access token, sent as a Bearer token. See authentication.
  • Safe retries: rate limits (429) are retried after the Retry-After seconds, and network failures are retried with a short backoff, 3 times by default. Every POST, PUT and PATCH carries an Idempotency-Key reused across retries, so a retried call never charges twice. See rate limits.
  • Typed results: responses become typed objects. The API's "yes", "no" and "unknown" flags become booleans, with null, None or nil for unknown, so "no" is never mistaken for true.
  • Bulk helpers: create jobs from a list of up to 100,000 addresses, upload CSV, TSV, TXT and XLSX files up to 50 MB with a free list health preview, wait with a progress callback, page or iterate through results, and download CSV or JSON with filters such as send_safe.
  • Webhooks: manage endpoints, and verify the X-RocketVerifier-Signature HMAC and timestamp of each delivery with one call.
  • Monitors, credits and account: schedule list health and domain authentication monitors, read your balance and fetch the account behind the credential.
  • OAuth: run the RocketVerifier Connect flow with PKCE and refresh access tokens automatically, with a callback to persist rotated refresh tokens. See OAuth.
  • Errors: one base error type per SDK with subclasses (or Go sentinels) for authentication, credits, rate limits, validation and more. See errors.

Compare capabilities#

Each row lists what the library implements today.

CapabilityNode.jsPythonGoPHPRubyCLI
Verify one addressYesYesYesYesYesYes
Server side verify timeout optionNoYesYesYesYesNo
Bulk job from a listYesYesYesYesYesYes
File and URL upload with preview and confirmYesYesYesYesYesYes
Wait for a job with progress updatesonProgresson_progressOnProgress$onProgressblock--wait
Progress with rate and ETAYesYesYesYesYesYes
Page through resultsYesYesYesYesYesYes
Iterate every resultAsync iteratorGeneratorIteratorGeneratorEnumeratorNo
Download CSV or JSON with filtersYesYesYesYesYesYes
Parse the CSV into typed rowsYesYesYesYesYesNo
Cancel a job with refundYesYesYesYesYesYes
Domain check (MX and disposable)YesYesYesYesYesNo
CreditsYesYesYesYesYesYes
Account (GET /v1/me)YesYesYesYesYesNo
MonitorsYesYesYesYesYesNo
Webhook endpoint managementYesYesYesYesYesNo
Webhook signature verificationYesYesYesYesYesNo
OAuth Connect with automatic refreshYesYesYesYesYesNo
Async clientPromisesAsyncRocketVerifiercontext.ContextNoNoNo
Retries 429YesYesYesYesYesYes
Retries network errorsYesYesYesYesYesNo
Retries timeoutsNoYesYesYesYesNo
Typed modelsTypeScriptDataclassesStructsReadonly classesClassesJSON output

Choose a library#

Prefer raw HTTP? The API reference documents every endpoint with cURL examples, and the quickstart gets a first verification running in five minutes.

Frequently asked questions

Which SDK should I use?

Use the library for your server language. All five SDKs cover the same API surface, so pick by language. Use the CLI for scripts, one-off checks and CI pipelines.

Do the SDKs read ROCKETVERIFIER_API_KEY automatically?

No. Pass the key to the client constructor, for example new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY). The CLI reads ROCKETVERIFIER_API_KEY on its own.

Can a retry charge me twice?

No. Every SDK and the CLI send an Idempotency-Key on writes and reuse it on every retry of that call, so the API returns the original result instead of charging again.

Can I call the API without an SDK?

Yes. The API is plain JSON over HTTPS with a Bearer key. The API reference has cURL examples for every endpoint.

Updated 11 November 2026Suggest an edit