# SDKs and CLI

Source: https://docs.rocketverifier.com/sdks

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

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.

Node.js:

```bash
npm install @rocketverifier/sdk
```

Python:

```bash
pip install rocketverifier
pip install "rocketverifier[async]"   # adds AsyncRocketVerifier
```

Go:

```bash
go get github.com/rocketverifier/sdk-go
```

PHP:

```bash
composer require rocketverifier/sdk
```

Ruby:

```bash
gem install rocketverifier
```

CLI:

```bash
npx @rocketverifier/cli verify deliverable@sandbox.rocketverifier.com
npm install -g @rocketverifier/cli
```

| Library | Package | Version | Requires | Runtime dependencies |
| --- | --- | --- | --- | --- |
| [Node.js](https://docs.rocketverifier.com/sdks/nodejs) | `@rocketverifier/sdk` | 2.2.1 | Node.js 18+ | None |
| [Python](https://docs.rocketverifier.com/sdks/python) | `rocketverifier` | 1.4.0 | Python 3.8+ | `requests`, plus `httpx` for async |
| [Go](https://docs.rocketverifier.com/sdks/go) | `github.com/rocketverifier/sdk-go` | 1.0.0 | Go 1.21+ | None |
| [PHP](https://docs.rocketverifier.com/sdks/php) | `rocketverifier/sdk` | 1.0.0 | PHP 8.1+ with curl | None |
| [Ruby](https://docs.rocketverifier.com/sdks/ruby) | `rocketverifier` | 1.0.0 | Ruby 2.6+ | None |
| [CLI](https://docs.rocketverifier.com/sdks/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.

Node.js:

```js
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);
```

Python:

```python
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)
```

Go:

```go
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)
```

PHP:

```php
$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);
```

Ruby:

```ruby
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.disposable
```

CLI:

```bash
export ROCKETVERIFIER_API_KEY="rv_test_your_key_here"
rocketverifier verify deliverable@sandbox.rocketverifier.com --json
```

cURL:

```bash
curl -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_` or `rv_test_`) or an OAuth access token, sent as a Bearer token. See [authentication](https://docs.rocketverifier.com/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](https://docs.rocketverifier.com/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](https://docs.rocketverifier.com/oauth).
- **Errors:** one base error type per SDK with subclasses (or Go sentinels) for authentication, credits, rate limits, validation and more. See [errors](https://docs.rocketverifier.com/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

- [Node.js](https://docs.rocketverifier.com/sdks/nodejs)
TypeScript types, ESM and CommonJS, zero dependencies.
- [Python](https://docs.rocketverifier.com/sdks/python)
Sync and async clients with dataclass results.
- [Go](https://docs.rocketverifier.com/sdks/go)
Standard library only, context on every call.
- [PHP](https://docs.rocketverifier.com/sdks/php)
PHP 8.1 readonly models, pluggable HTTP client.
- [Ruby](https://docs.rocketverifier.com/sdks/ruby)
Standard library only, idiomatic keywords and blocks.
- [CLI](https://docs.rocketverifier.com/sdks/cli)
Verify, run bulk jobs and gate CI from the terminal.

Prefer raw HTTP? The [API reference](https://docs.rocketverifier.com/api) documents every endpoint with cURL examples, and the [quickstart](https://docs.rocketverifier.com/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](/api) has cURL examples for every endpoint.
