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/sdkpip install rocketverifier
pip install "rocketverifier[async]" # adds AsyncRocketVerifiergo get github.com/rocketverifier/sdk-gocomposer require rocketverifier/sdkgem install rocketverifiernpx @rocketverifier/cli verify deliverable@sandbox.rocketverifier.com
npm install -g @rocketverifier/cli| Library | Package | Version | Requires | Runtime dependencies |
|---|---|---|---|---|
| Node.js | @rocketverifier/sdk | 2.2.1 | Node.js 18+ | None |
| Python | rocketverifier | 1.4.0 | Python 3.8+ | requests, plus httpx for async |
| Go | github.com/rocketverifier/sdk-go | 1.0.0 | Go 1.21+ | None |
| PHP | rocketverifier/sdk | 1.0.0 | PHP 8.1+ with curl | None |
| Ruby | rocketverifier | 1.0.0 | Ruby 2.6+ | None |
| CLI | @rocketverifier/cli | 1.1.0 | Node.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);import os
from rocketverifier import RocketVerifier
rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])
result = rv.verify("deliverable@sandbox.rocketverifier.com")
print(result.status, result.sub_status, result.domain.disposable)rv, err := rocketverifier.New(os.Getenv("ROCKETVERIFIER_API_KEY"))
if err != nil {
log.Fatal(err)
}
result, err := rv.Verify(context.Background(), "deliverable@sandbox.rocketverifier.com", nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Status, result.SubStatus, result.Domain.Disposable)$rv = new RocketVerifier\RocketVerifier(getenv('ROCKETVERIFIER_API_KEY'));
$result = $rv->verify('deliverable@sandbox.rocketverifier.com');
echo $result->status, ' ', $result->subStatus, "\n";
var_dump($result->domain->disposable);require "rocketverifier"
rv = RocketVerifier::Client.new(ENV.fetch("ROCKETVERIFIER_API_KEY"))
result = rv.verify("deliverable@sandbox.rocketverifier.com")
puts result.status, result.sub_status, result.domain.disposableexport ROCKETVERIFIER_API_KEY="rv_test_your_key_here"
rocketverifier verify deliverable@sandbox.rocketverifier.com --jsoncurl -X POST https://api.rocketverifier.com/v1/verify \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "deliverable@sandbox.rocketverifier.com"}'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_orrv_test_) or an OAuth access token, sent as a Bearer token. See authentication. - Safe retries: rate limits (429) are retried after the
Retry-Afterseconds, and network failures are retried with a short backoff, 3 times by default. Every POST, PUT and PATCH carries anIdempotency-Keyreused 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, withnull,Noneornilfor 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-SignatureHMAC 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.
| Capability | Node.js | Python | Go | PHP | Ruby | CLI |
|---|---|---|---|---|---|---|
| Verify one address | Yes | Yes | Yes | Yes | Yes | Yes |
| Server side verify timeout option | No | Yes | Yes | Yes | Yes | No |
| Bulk job from a list | Yes | Yes | Yes | Yes | Yes | Yes |
| File and URL upload with preview and confirm | Yes | Yes | Yes | Yes | Yes | Yes |
| Wait for a job with progress updates | onProgress | on_progress | OnProgress | $onProgress | block | --wait |
| Progress with rate and ETA | Yes | Yes | Yes | Yes | Yes | Yes |
| Page through results | Yes | Yes | Yes | Yes | Yes | Yes |
| Iterate every result | Async iterator | Generator | Iterator | Generator | Enumerator | No |
| Download CSV or JSON with filters | Yes | Yes | Yes | Yes | Yes | Yes |
| Parse the CSV into typed rows | Yes | Yes | Yes | Yes | Yes | No |
| Cancel a job with refund | Yes | Yes | Yes | Yes | Yes | Yes |
| Domain check (MX and disposable) | Yes | Yes | Yes | Yes | Yes | No |
| Credits | Yes | Yes | Yes | Yes | Yes | Yes |
Account (GET /v1/me) | Yes | Yes | Yes | Yes | Yes | No |
| Monitors | Yes | Yes | Yes | Yes | Yes | No |
| Webhook endpoint management | Yes | Yes | Yes | Yes | Yes | No |
| Webhook signature verification | Yes | Yes | Yes | Yes | Yes | No |
| OAuth Connect with automatic refresh | Yes | Yes | Yes | Yes | Yes | No |
| Async client | Promises | AsyncRocketVerifier | context.Context | No | No | No |
| Retries 429 | Yes | Yes | Yes | Yes | Yes | Yes |
| Retries network errors | Yes | Yes | Yes | Yes | Yes | No |
| Retries timeouts | No | Yes | Yes | Yes | Yes | No |
| Typed models | TypeScript | Dataclasses | Structs | Readonly classes | Classes | JSON output |
Choose a library#
TypeScript types, ESM and CommonJS, zero dependencies.
PythonSync and async clients with dataclass results.
GoStandard library only, context on every call.
PHPPHP 8.1 readonly models, pluggable HTTP client.
RubyStandard library only, idiomatic keywords and blocks.
CLIVerify, run bulk jobs and gate CI from the terminal.
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