# RocketVerifier Documentation (complete) > Every page of docs.rocketverifier.com in reading order. Base URL https://api.rocketverifier.com/v1, Bearer API key auth. # RocketVerifier Docs: Email Verification API, SDKs and Integrations Source: https://docs.rocketverifier.com > RocketVerifier is an email verification API. One request tells you whether an address is deliverable, undeliverable, risky or unknown, why, and the evidence behind the verdict. Verify one address in real time, clean lists of up to 100,000 per job, or sync results into your CRM. RocketVerifier checks whether an email address can receive mail before you send to it. Every result has a `status` (deliverable, undeliverable, risky or unknown), a `sub_status` with the precise reason, a 0 to 100 `score` and the evidence from DNS, list and SMTP checks. Unknown results are never charged. ## Start here - [Quickstart](https://docs.rocketverifier.com/quickstart): create a key and verify your first address in 5 minutes. - [Authentication](https://docs.rocketverifier.com/authentication): API keys, sandbox keys and OAuth tokens. - [Reading results](https://docs.rocketverifier.com/results): what every status and sub_status means and costs. ## What you can build - **Verify at signup:** real-time checks on forms with [RocketShield](https://docs.rocketverifier.com/integrations/widget) or [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify). - **Clean a list:** [upload a file](https://docs.rocketverifier.com/api/bulk-upload), get a free list health preview, then verify up to 100,000 emails per job. - **Keep a CRM clean:** [native connectors](https://docs.rocketverifier.com/integrations) for HubSpot, Salesforce, Mailchimp and more, synced on a schedule. - **Verify from AI assistants:** connect the [MCP server](https://docs.rocketverifier.com/mcp) to Claude, Cursor or any MCP client. - **Build an app:** use [RocketVerifier Connect](https://docs.rocketverifier.com/oauth) (OAuth 2.0 with PKCE) to act for other RocketVerifier users. - **React to events:** [webhooks](https://docs.rocketverifier.com/api/webhooks) for finished jobs, low credits and list monitor alerts. ## Libraries Official SDKs for [Node.js](https://docs.rocketverifier.com/sdks/nodejs), [Python](https://docs.rocketverifier.com/sdks/python), [Go](https://docs.rocketverifier.com/sdks/go), [PHP](https://docs.rocketverifier.com/sdks/php) and [Ruby](https://docs.rocketverifier.com/sdks/ruby), plus a [command line tool](https://docs.rocketverifier.com/sdks/cli). --- # Verify your first email in 5 minutes Source: https://docs.rocketverifier.com/quickstart > Create an API key in the dashboard, send one POST request to https://api.rocketverifier.com/v1/verify with the address, and branch on the status field. Use sandbox addresses to test for free. You need a RocketVerifier account and about five minutes. By the end you will have verified a real address and know what to do with each result. **Step 1. Create an API key** Open [API keys](https://app.rocketverifier.com/dashboard/api-keys) in the dashboard and create a key. Live keys start with `rv_live_` and verify any address. Sandbox keys start with `rv_test_` and only accept sandbox addresses, which makes them safe for CI. Store the key in an environment variable and pass it to the client. Every example in these docs reads `ROCKETVERIFIER_API_KEY`, and the CLI picks it up automatically. ```bash export ROCKETVERIFIER_API_KEY="rv_live_your_key_here" ``` **Step 2. Install an SDK (optional)** Node.js: ```bash npm install @rocketverifier/sdk ``` Python: ```bash pip install rocketverifier ``` cURL: ```bash # Nothing to install ``` **Step 3. Verify an address** Start with a sandbox address. It returns a fixed result and costs nothing, so you can check your integration before you spend a credit. 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); // "deliverable" console.log(result.subStatus); // "none" console.log(result.score); // 95 ``` 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) # "deliverable" print(result.sub_status) # "none" print(result.score) # 95 ``` 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"}' ``` Then swap in a real address. Real addresses need a live key and use 1 credit per result, except `unknown` results, which are free. **Step 4. Act on the result** Branch on `status`. It always holds one of four values, and the decision for each is the same in every product. | status | What to do | Meaning | Cost | | --- | --- | --- | --- | | `deliverable` | Send | The mail server explicitly accepted the mailbox. | 1 credit | | `undeliverable` | Remove | The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable. | 1 credit | | `risky` | Send with care | The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals. | 1 credit | | `unknown` | Retry later | The mail server gave no conclusive answer. Retry after retry_after seconds. | Free | Node.js: ```js switch (result.status) { case "deliverable": return accept(email); case "risky": // catch-all, role address, full mailbox: accept, but flag for review return acceptWithFlag(email, result.subStatus); case "undeliverable": return reject(email, result.didYouMean ? `Did you mean ${result.didYouMean}?` : undefined); case "unknown": // free: check again later return queueRetry(email); } ``` ## Try it now No key needed. These calls hit the live API with sandbox addresses. Try the sandbox addresses live at https://docs.rocketverifier.com/api/verify#try-it (no key needed). ## Next steps - [Reading results](https://docs.rocketverifier.com/results) Every status and sub_status, what it costs and what to do with it. - [Verify a list in bulk](https://docs.rocketverifier.com/api/bulk-upload) Upload a file, get a free list health preview, then verify up to 100,000 emails per job. - [Verify at signup](https://docs.rocketverifier.com/guides/signup-verification) Block bad addresses on your forms with RocketShield or a server-side check. - [Webhooks](https://docs.rocketverifier.com/api/webhooks) Get a signed event when a bulk job finishes instead of polling. ## Frequently asked questions ### Do I need a credit card to start? No. Sign up, create a key and test with sandbox addresses for free. Buy credits when you are ready to verify real addresses. ### Which status means I can send? `deliverable` means the mail server confirmed the mailbox. Treat `risky` with care, remove `undeliverable`, and retry `unknown` later at no cost. ### Should I use the SDK or plain HTTP? Either. The SDKs add retries on rate limits, typed results and helpers for bulk jobs and webhooks. Plain HTTP works from any language with one POST request. --- # Authentication Source: https://docs.rocketverifier.com/authentication > Send your API key in the Authorization header as Bearer rv_live_... on every request. Live keys verify any address; sandbox keys (rv_test_) only accept sandbox addresses and never charge. Each key can carry its own permissions, expiry date, IP allowlist and monthly credit cap. Apps acting for other users send an OAuth access token (rv_at_) the same way. Every request to `https://api.rocketverifier.com/v1` carries one credential in the `Authorization` header. The credential decides which account is billed, what the request is allowed to do and which rate limit applies. ## Create an API key Open [API keys](https://app.rocketverifier.com/dashboard/api-keys) in the dashboard and click **Create API key**. Give it a name that says where it runs, such as "Production signup server", and choose its settings: | Setting | What it does | | --- | --- | | Permissions | The scopes the key can use. All eight are selected by default. | | Expiry date | Optional. The key stops working at this date. | | Monthly credit limit | Optional. The most credits the key can spend per calendar month (UTC). | | Allowed IPs | Optional. IPv4 and IPv6 addresses or CIDR ranges the key accepts requests from. | | Sandbox key | Creates an `rv_test_` key that only accepts sandbox addresses. | Copy the key when it appears: it is shown once. RocketVerifier stores only a SHA-256 hash, and emails the account owner whenever a key is created, rotated or revoked. Each account holds up to 25 keys. ## Send the key Put the key in the `Authorization` header with the `Bearer` scheme. The SDKs and the CLI read `ROCKETVERIFIER_API_KEY` from the environment. cURL: ```bash curl https://api.rocketverifier.com/v1/me \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); const me = await rv.getMe(); console.log(me.email, me.credits); ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) me = rv.get_me() print(me.email, me.credits) ``` `GET /v1/me` is the quickest way to check a credential: it returns the account it acts as, its balance and its scopes, and works even at a zero balance. The [account reference](https://docs.rocketverifier.com/api/account) has the full response. The `/v1` endpoints accept the `Authorization` header only. An `X-API-Key` header is ignored there. ## Credential types The prefix tells you what a credential is and how it is billed. | Prefix | Credential | Billed to | Use it for | | --- | --- | --- | --- | | `rv_live_` | Live API key | Your account | Production and real addresses | | `rv_test_` | Sandbox key | Never charged | CI, staging and demos with [sandbox addresses](https://docs.rocketverifier.com/sandbox) | | `rv_at_` | OAuth access token | The account that connected your app | Apps acting for other RocketVerifier users ([Connect](https://docs.rocketverifier.com/oauth)) | Organization API keys belong to a team instead of a person. They act as the organization, spend its shared credit pool and share one rate limit bucket. See [organization keys](#organization-api-keys) below. ## Permissions Each key carries a set of scopes, and every endpoint checks one. A key without the scope gets `403 insufficient_scope`. | Scope | Allows | | --- | --- | | `verify:single` | `POST /v1/verify`, `POST /v1/finder` | | `verify:bulk` | `POST /v1/verify/bulk`, file uploads, previews and confirmations | | `jobs:read` | Listing jobs, job status, progress, results and downloads | | `jobs:write` | Cancelling and deleting jobs | | `webhooks:manage` | Creating, updating, testing and deleting webhooks | | `credits:read` | `GET /v1/credits` | | `monitors:read` | Listing monitors and their runs | | `monitors:write` | Creating, updating, deleting and running monitors | Give each key only what its service needs. A signup server needs `verify:single` and nothing else. OAuth apps request scopes on the consent screen, including `account:read`; see [OAuth scopes](https://docs.rocketverifier.com/oauth/scopes). ## Expiry dates A key with an expiry date stops working at that moment and returns `401 api_key_expired`. Use expiry for contractors, trials and one-off migrations, so access ends without anyone remembering to revoke it. Set, extend or clear the date by editing the key. The change applies to the existing secret at once. ## IP allowlists A key with an allowlist only accepts requests from the listed addresses. Add up to 50 IPv4 or IPv6 addresses or CIDR ranges, such as `203.0.113.7` or `10.20.0.0/16`. An empty list accepts any address. Requests from other addresses get `403 ip_not_allowed`, with the caller's IP in the message so you can add it. If the client IP cannot be determined, the request is rejected too: the allowlist always fails closed. Organization keys use the organization's allowlist instead, and it also applies to OAuth tokens issued for the organization. ## Monthly spend caps A monthly credit limit caps what one key can spend per calendar month (UTC), from 1 to 100,000,000 credits. A leaked key or a runaway loop stops at the cap instead of draining the balance. - **Enforced at charge time.** Each charge reserves quota atomically, so concurrent requests never overshoot the cap. - **Refunds count.** Unknown results, failed jobs and cancelled jobs give their quota back. - **Whole jobs.** A bulk job is accepted only if all of its unique addresses fit under the remaining cap. - **Resets** on the first day of each month at 00:00 UTC. A request over the cap gets `402 api_key_spend_cap_reached`: 402 api_key_spend_cap_reached: ```json { "error": { "code": "api_key_spend_cap_reached", "message": "This API key or app connection has reached its monthly credit limit", "details": { "monthly_limit": 5000, "used_this_month": 4998, "required": 10 } } } ``` Sandbox keys never spend credits, so caps do not apply to them. OAuth connections carry their own monthly cap, set by the user who connected the app. ## Rotate or revoke a key **Rotate** a key to replace its secret and keep everything else: name, permissions, expiry, allowlist, cap and usage history. The old secret stops working immediately, so deploy the new one first. **Delete** a key to revoke it for good. Both actions are in the key's menu under [API keys](https://app.rocketverifier.com/dashboard/api-keys), and both send a security email to the account owner. ## Organization API keys An organization key belongs to a team. It authenticates as the organization's owner, spends the organization's shared credit pool first when pooling is on, and uses one rate limit bucket for the whole organization, separate from members' personal keys. Its allowlist is the organization's IP allowlist. Use organization keys for shared services, so nobody's personal key sits in a team server. [Teams](https://docs.rocketverifier.com/teams) covers organizations, roles and pooled credits. ## OAuth access tokens Apps that act for other RocketVerifier users use [RocketVerifier Connect](https://docs.rocketverifier.com/oauth) instead of asking for an API key. The user approves your app, and you send the access token exactly like a key: cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify \ -H "Authorization: Bearer rv_at_your_access_token" \ -H "Content-Type: application/json" \ -d '{"email": "maya@northwind.io"}' ``` Calls are billed to the account that connected and limited to the [scopes](https://docs.rocketverifier.com/oauth/scopes) it approved. When an access token expires or is revoked, the API returns `401 invalid_token` with a `WWW-Authenticate: Bearer error="invalid_token"` header. Refresh it with the `rv_rt_` refresh token; the Node.js and Python SDKs do this for you when you pass the refresh token and an OAuth client. ## Keep keys secure - **Server side only.** Never ship an API key in a browser, mobile app or public repository. Use [RocketShield](https://docs.rocketverifier.com/integrations/widget) for forms. - **One key per service and environment.** Separate keys can be capped, restricted and rotated on their own. - **Least privilege.** Grant only the scopes a service uses. - **Restrict and cap.** Add an IP allowlist for servers with fixed addresses, and a monthly credit limit on every production key. - **Store keys as secrets.** Use your platform's secret store or environment variables, never source code. - **Rotate on any doubt.** If a key appears in a log, a ticket or a commit, rotate it right away. ## Authentication errors Every error uses the [standard error shape](https://docs.rocketverifier.com/errors). These are the ones a credential can cause: | Status | `error.code` | Cause | Fix | | --- | --- | --- | --- | | 401 | `unauthorized` | No `Authorization` header, a header without `Bearer `, or an unknown or revoked key | Send `Authorization: Bearer ` with an active key | | 401 | `api_key_expired` | The key passed its expiry date | Extend the date or create a new key | | 401 | `invalid_token` | The OAuth access token expired, was revoked or its app was suspended | Refresh the token, or send the user through Connect again | | 403 | `ip_not_allowed` | The caller's IP is not on the key's or organization's allowlist | Add the IP or CIDR range to the allowlist | | 403 | `insufficient_scope` | The key or token lacks the scope this endpoint needs | Add the scope to the key, or request it in your OAuth app | | 403 | `sandbox_key_restricted` | An `rv_test_` key was used on a real address or an upload | Use a live key, or a sandbox address | | 403 | `insufficient_credits` | The balance is zero on an endpoint that spends credits | Buy credits, or turn on auto-recharge | | 403 | `account_suspended` | The account is suspended | Contact support@rocketverifier.com | | 402 | `api_key_spend_cap_reached` | The key's monthly credit limit is used up | Raise the limit or wait for the next month | ## Next steps - [Sandbox and testing](https://docs.rocketverifier.com/sandbox) Test with fixed results and keys that never charge. - [Rate limits](https://docs.rocketverifier.com/rate-limits) Requests per minute for each plan, and how to handle 429. - [Build an app](https://docs.rocketverifier.com/oauth) Act for other users with OAuth instead of API keys. - [Errors](https://docs.rocketverifier.com/errors) Every error code, its cause and how to recover. ## Frequently asked questions ### Can I use the X-API-Key header? No. The /v1 endpoints read the key from the Authorization header only, as Bearer followed by the key. Requests with only X-API-Key are rejected with 401 unauthorized. ### Can I see a key again after creating it? No. The key is shown once, and RocketVerifier stores only a SHA-256 hash of it. If you lose a key, rotate it to get a new secret with the same settings. ### Can I call the API from a browser? Not with an API key, because anyone could copy it from the page. For forms, use RocketShield, which runs on a public key restricted to your domains. Keep API keys on your server. ### How many API keys can I create? Up to 25 per account. Use one key per service and environment, so each can be capped, restricted and rotated on its own. ### Does changing a key's settings require a new key? No. Permissions, expiry, IP allowlist and monthly cap apply to the existing secret as soon as you save, with nothing to redeploy. --- # Sandbox and testing Source: https://docs.rocketverifier.com/sandbox > Addresses at @sandbox.rocketverifier.com return a fixed status, sub_status and score from POST /v1/verify, free and without an API key. Sandbox keys (rv_test_) only accept sandbox addresses and never spend credits, which makes them the right key for CI, staging and demos. Testing an email verifier against real addresses is slow, costs credits and gives answers that change over time. The sandbox fixes all three: eight addresses with fixed answers, and keys that cannot touch anything else. ## Sandbox addresses Each address below returns the same `status`, `sub_status` and `score` every time, from the live API. | Address | status | sub_status | score | | --- | --- | --- | --- | | `deliverable@sandbox.rocketverifier.com` | deliverable | `none` | 95 | | `valid@sandbox.rocketverifier.com` | deliverable | `none` | 98 | | `undeliverable@sandbox.rocketverifier.com` | undeliverable | `mailbox_not_found` | 0 | | `invalid@sandbox.rocketverifier.com` | undeliverable | `mailbox_not_found` | 0 | | `disposable@sandbox.rocketverifier.com` | undeliverable | `disposable` | 10 | | `risky@sandbox.rocketverifier.com` | risky | `catch_all` | 45 | | `admin@sandbox.rocketverifier.com` | risky | `role_based` | 60 | | `unknown@sandbox.rocketverifier.com` | unknown | `smtp_unavailable` | 30 | Matching ignores case and surrounding spaces. The risky catch-all address also returns `catch_all_verdict: "send_with_caution"`, so you can test catch-all handling. Only these eight addresses return fixed results; any other address at the sandbox domain is verified like a real one. ## Try it No key needed. Pick an address and see the full response. Try the sandbox addresses live at https://docs.rocketverifier.com/api/verify#try-it (no key needed). ## Call the sandbox without a key `POST /v1/verify` answers sandbox addresses before it checks credentials, so they work with no key, a live key or a sandbox key, and never cost a credit. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify \ -H "Content-Type: application/json" \ -d '{"email": "undeliverable@sandbox.rocketverifier.com"}' ``` Response 200 (excerpt): ```json { "email": "undeliverable@sandbox.rocketverifier.com", "status": "undeliverable", "reason": "rejected_email", "sub_status": "mailbox_not_found", "score": 0, "catch_all_verdict": null, "did_you_mean": null, "provider": "sandbox.rocketverifier.com", "verified_at": "2026-11-11T09:42:17.204Z" } ``` Requests without a key count against the anonymous limit of 5 per minute per IP address. Send a key, live or sandbox, to get your plan's [rate limit](https://docs.rocketverifier.com/rate-limits) instead. ## Sandbox keys A sandbox key starts with `rv_test_`. It never charges credits and only accepts sandbox addresses, so a test suite, staging server or demo can never verify real data by mistake. Create one under [API keys](https://app.rocketverifier.com/dashboard/api-keys) by ticking **Sandbox key (rv_test_...)**. It takes the same permissions, expiry date and IP allowlist as a live key. | Endpoint | With an `rv_test_` key | | --- | --- | | `POST /v1/verify` | Sandbox addresses only. Any other address returns `403 sandbox_key_restricted`. | | `POST /v1/verify/bulk` | Jobs made only of sandbox addresses. One real address rejects the whole job with `403 sandbox_key_restricted` and `details.non_sandbox_count`. | | `POST /v1/verify/bulk/upload` | Not available. Returns `403 sandbox_key_restricted`; use `POST /v1/verify/bulk` with sandbox addresses. | | `POST /v1/finder` | Domain `sandbox.rocketverifier.com` only, with a fixed `found` result. | | Read endpoints (jobs, credits, webhooks, monitors) | Work as usual. | 403 sandbox_key_restricted: ```json { "error": { "code": "sandbox_key_restricted", "message": "Sandbox API keys (rv_test_*) can only verify @sandbox.rocketverifier.com test addresses. Use a live key (rv_live_*) to verify real email addresses.", "details": null } } ``` Every authenticated request needs an account balance of at least 1 credit, sandbox keys included. Sandbox requests never spend it. ## Test bulk jobs A bulk job submitted with a sandbox key runs end to end at no cost: the job is created, processed, fires the `job.completed` webhook and can be downloaded. Use it to test your job lifecycle code. Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_TEST_KEY); // rv_test_... const job = await rv.batch.create({ emails: [ "deliverable@sandbox.rocketverifier.com", "risky@sandbox.rocketverifier.com", "unknown@sandbox.rocketverifier.com", ], name: "CI smoke test", }); console.log(job.creditsToUse); // 0 const done = await rv.batch.wait(job.id); console.log(done.status); // "completed" ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_TEST_KEY"]) # rv_test_... job = rv.batch.create( [ "deliverable@sandbox.rocketverifier.com", "risky@sandbox.rocketverifier.com", "unknown@sandbox.rocketverifier.com", ], name="CI smoke test", ) print(job.credits_to_use) # 0 done = rv.batch.wait(job.id) print(done.status) # "completed" ``` The fixed results in the table above come from `POST /v1/verify`. When a test asserts an exact `status` or `sub_status`, verify the address on its own. To test your webhook handler with a signed event, call [`POST /v1/webhooks/{id}/test`](https://docs.rocketverifier.com/api/webhooks). ## Use the sandbox in CI Run your integration tests against the live API with a sandbox key: the requests are real, the answers are fixed, and nothing is charged. **Step 1. Create a sandbox key for CI** Create an `rv_test_` key named after the pipeline, and store it as a secret such as `ROCKETVERIFIER_TEST_KEY`. Give it only the permissions your tests use. **Step 2. Assert on fixed results** Node.js: ```js import { describe, expect, it } from "vitest"; import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_TEST_KEY); describe("signup verification", () => { it("accepts a deliverable address", async () => { const r = await rv.verify("deliverable@sandbox.rocketverifier.com"); expect(r.status).toBe("deliverable"); expect(r.subStatus).toBe("none"); }); it("blocks a disposable address", async () => { const r = await rv.verify("disposable@sandbox.rocketverifier.com"); expect(r.status).toBe("undeliverable"); expect(r.subStatus).toBe("disposable"); }); it("flags a role address", async () => { const r = await rv.verify("admin@sandbox.rocketverifier.com"); expect(r.status).toBe("risky"); expect(r.subStatus).toBe("role_based"); }); }); ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_TEST_KEY"]) def test_accepts_deliverable(): r = rv.verify("deliverable@sandbox.rocketverifier.com") assert r.status == "deliverable" assert r.sub_status == "none" def test_blocks_disposable(): r = rv.verify("disposable@sandbox.rocketverifier.com") assert r.status == "undeliverable" assert r.sub_status == "disposable" def test_flags_role_address(): r = rv.verify("admin@sandbox.rocketverifier.com") assert r.status == "risky" assert r.sub_status == "role_based" ``` **Step 3. Cover the unknown path** `unknown@sandbox.rocketverifier.com` returns `unknown` with `sub_status: "smtp_unavailable"`. Use it to test your retry queue without waiting for a real mail server to time out. Keep unit tests offline by stubbing the client, and run these live sandbox tests as a small smoke suite. Requests count against the key's [rate limit](https://docs.rocketverifier.com/rate-limits) like any other. ## Next steps - [Authentication](https://docs.rocketverifier.com/authentication) Live keys, sandbox keys, expiry, IP allowlists and spend caps. - [Reading results](https://docs.rocketverifier.com/results) What every status and sub_status means and costs. ## Frequently asked questions ### Do sandbox addresses need an API key? Not on POST /v1/verify. The eight sandbox addresses return their fixed result with or without a key, and never cost a credit. Requests without a key share the anonymous limit of 5 per minute per IP, so send a key in automated tests. ### What is the difference between a sandbox address and a sandbox key? A sandbox address is a test input that returns a fixed result. A sandbox key (rv_test_) is a credential that only accepts sandbox addresses and never charges, so a misconfigured test can never verify real data or spend credits. ### Can I run bulk jobs in the sandbox? Yes. POST /v1/verify/bulk with an rv_test_ key accepts jobs made only of @sandbox.rocketverifier.com addresses and never charges them. Use them to test job creation, polling, webhooks and downloads. Assert exact statuses with POST /v1/verify. ### Why does my sandbox key get 403 insufficient_credits? Every authenticated request needs an account balance of at least 1 credit, sandbox keys included. Sandbox requests never spend it. New accounts start with 100 free credits. --- # Reading verification results Source: https://docs.rocketverifier.com/results > Branch on status, which always holds one of four values. Read sub_status for the precise reason, score for a calibrated 0 to 100 chance of delivery, catch_all_verdict for accept-all domains and did_you_mean for typos. Deliverable, undeliverable and risky results cost 1 credit; unknown results are free and carry a retry_after hint. Every result answers three questions: can I send to this address (`status`), why (`sub_status`), and how confident is the verdict (`score`). The rest of the fields help you segment lists, explain decisions to users and debug edge cases. ## What a result contains A result is one JSON object with a fixed set of fields. These are the ones that drive decisions: | Field | Type | Use it for | | --- | --- | --- | | `status` | string | The decision. Always `deliverable`, `undeliverable`, `risky` or `unknown`. | | `sub_status` | string | The precise reason, one of 25 values. `none` when there is nothing to add. | | `score` | integer 0 to 100 | Calibrated chance the address delivers. Use it to rank and threshold. | | `deliverability_tier` | string | The score band: `excellent`, `good`, `fair`, `poor` or `unknown`. | | `catch_all_verdict` | string or null | `send_safe`, `send_with_caution` or `avoid` on accept-all domains. | | `did_you_mean` | string or null | A corrected address when the input looks like a typo. | | `retry_after` | integer or null | Seconds to wait before retrying an `unknown` result. | | `verdict_source` | string | Where the verdict came from: `smtp`, `dns`, `syntax`, `list`, `precheck` or `cache`. | | `verified_at` | ISO 8601 | When the verdict was produced. | The full field list, including `domain`, `account`, `smtp_provider`, `gateway` and `evidence`, is in the [verify reference](https://docs.rocketverifier.com/api/verify#response). ## Status `status` is the only field you need to branch on. It always holds one of four values, and the action for each is the same in every product. | status | What to do | Meaning | Cost | | --- | --- | --- | --- | | `deliverable` | Send | The mail server explicitly accepted the mailbox. | 1 credit | | `undeliverable` | Remove | The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable. | 1 credit | | `risky` | Send with care | The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals. | 1 credit | | `unknown` | Retry later | The mail server gave no conclusive answer. Retry after retry_after seconds. | Free | Only an explicit answer from the mail server produces `deliverable` or `undeliverable`. When a server blocks the check, greylists it or times out, the result is `unknown` and free, instead of a guess. Catch-all addresses are `risky` under the current [result version](https://docs.rocketverifier.com/versioning), `2026-11-01`. Keys created before November 2026 use `2025-01-01`, which reports them as `unknown`. Send the `RocketVerifier-Version: 2026-11-01` header to get the current mapping on any key. ## Sub status `sub_status` names the single most important reason behind the status, so two addresses with the same status can be treated differently. The table lists all 25 values with the status each one belongs to and its cost. | sub_status | status | Meaning | Cost | | --- | --- | --- | --- | | `none` | deliverable | Mailbox confirmed, no other flags. | 1 credit | | `alias` | deliverable | Mailbox confirmed. The address is sub-addressed (name+tag@). | 1 credit | | `forwarder` | deliverable | Mailbox confirmed on a forwarding service that relays to another inbox. | 1 credit | | `mailbox_not_found` | undeliverable | The mail server rejected the mailbox, for example 5.1.1 user unknown. | 1 credit | | `account_disabled` | undeliverable | The mailbox exists but is disabled. | 1 credit | | `does_not_accept_mail` | undeliverable | The domain does not accept mail: null MX, no mail route, or a 521 reply. | 1 credit | | `invalid_syntax` | undeliverable | The address is not syntactically valid. | 1 credit | | `invalid_domain` | undeliverable | The domain does not exist (NXDOMAIN). | 1 credit | | `disposable` | undeliverable | A disposable or temporary inbox provider. | 1 credit | | `catch_all` | risky | The domain accepts every address. Read catch_all_verdict for a per-address recommendation. | 1 credit | | `role_based` | risky | A role address such as info@ or support@ that reaches a team, not a person. | 1 credit | | `mailbox_full` | risky | The mailbox exists but is over quota. | 1 credit | | `possible_trap` | risky | Matches spam trap signals. | 1 credit | | `toxic` | risky | The address is linked to abuse, complaints or bot signups. | 1 credit | | `do_not_mail` | risky | A known complainer, or an address on your own suppression list. | 1 credit, free for your suppression list | | `accepts_then_bounces` | risky | The server accepts at SMTP time but this mailbox is known to bounce later. | 1 credit | | `privacy_relay` | risky | A privacy relay address (SimpleLogin or addy.io) that forwards to a hidden inbox. | 1 credit | | `parked_domain` | risky | The domain is parked and unlikely to have a monitored inbox. | 1 credit | | `possible_typo` | risky | Likely a typo. did_you_mean holds the suggested address. Reported as unknown, and free, when the mailbox could not be checked. | 1 credit | | `dns_error` | unknown | DNS lookup failed temporarily (SERVFAIL or timeout). | Free | | `greylisted` | unknown | The mail server asked us to retry later. | Free | | `blocked` | unknown | The mail server refused the check: policy, blocklist or reputation rejection such as 5.7.x. | Free | | `smtp_timeout` | unknown | The SMTP conversation timed out. | Free | | `no_connect` | unknown | Could not connect to the mail server. | Free | | `smtp_unavailable` | unknown | No conclusive SMTP answer for another reason. | Free | When several reasons apply, the strongest wins: suppression first, then syntax, disposable domains, DNS failures, mailbox rejections, transient SMTP failures and finally the risk signals (traps, complaints, typos, catch-all, role). A role address on a catch-all domain is reported as `catch_all`, for example. The older `reason` field is still returned for existing integrations. It is derived from `sub_status`, so the two always agree, but `sub_status` is more precise. New code should read `sub_status`. ### Transient unknowns and their retry hints Six `unknown` sub statuses are temporary, and each has a default `retry_after`: | `sub_status` | Default `retry_after` | What happened | | --- | --- | --- | | `dns_error` | 60 seconds | DNS lookup failed temporarily. | | `smtp_timeout` | 60 seconds | The mail server did not answer in time. | | `smtp_unavailable` | 120 seconds | No conclusive SMTP answer for another reason. | | `greylisted` | 300 seconds | The server asked for a retry later. When it names a wait, that value is used (60 to 1,800 seconds). | | `no_connect` | 300 seconds | The mail server refused the connection. | | `blocked` | 900 seconds | The server refused the check by policy or reputation (for example 5.7.x). | Bulk jobs retry greylisted addresses for you, up to three times about ten minutes apart, before they report a final result. ## Score and deliverability tier `score` is a calibrated probability from 0 to 100: a score of 80 means about 80 percent of addresses with the same signals delivered. It is fitted on mailboxes with a known answer and on real bounce outcomes from connected sending platforms. For every address that reaches the mailbox check, the score agrees with the status: - **Rejected mailboxes** (`mailbox_not_found`, `account_disabled`) are capped at 10. - **Unknown** results are capped at 60. - **Toxic** addresses are capped at 40. Results decided before the mailbox check (bad syntax, a disposable provider, a domain that does not exist) carry a fixed score that reflects confidence in that verdict. Branch on `status` first and use `score` to rank addresses within a status, never on its own. `deliverability_tier` is a label for the score band, handy for spreadsheets and CRM fields: | Tier | Score | | --- | --- | | `excellent` | 85 to 100 | | `good` | 70 to 84 | | `fair` | 45 to 69 | | `poor` | 20 to 44 | | `unknown` | below 20 | Results decided by syntax, suppression, disposable or DNS checks report `deliverability_tier: "unknown"`. The domain's SPF, DKIM and DMARC posture is reported separately in `authentication_score`. ## Catch-all verdict `catch_all_verdict` is set whenever the domain accepts mail for every address, and `null` otherwise. It is a per-address recommendation, not a domain flag. | catch_all_verdict | Meaning | | --- | --- | | `send_safe` | Resolution score 65 or higher: strong signals this mailbox is real and active. | | `send_with_caution` | Resolution score 35 to 64, or too little evidence to decide. Send to engaged segments or warm the address first. | | `avoid` | Resolution score below 35: signals point to a mailbox that does not exist. | The `catch_all` object adds the 0 to 100 resolution `score`, the `method` (`pattern` or `heuristic`) and up to five plain-language `reasons`. The [catch-all guide](https://docs.rocketverifier.com/catch-all) explains how the verdict is reached and how to act on each value. ## Typo suggestions `did_you_mean` holds a full corrected address when the domain looks like a typo of a known mail provider, for example `maya@gmail.com` for `maya@gmial.com`. It is never set on a `deliverable` result. - When the typo domain does not exist or receive mail, the result is `undeliverable` with `sub_status` `invalid_domain` or `does_not_accept_mail`, and `did_you_mean` carries the fix. - When the typo domain does receive mail (a known typo domain), the result is `risky` with `sub_status` `possible_typo`. If the mailbox could not be checked, it is `unknown` with `possible_typo`, and free. Show the suggestion and let the person confirm it. Never rewrite the address silently. ## Retry unknown results An `unknown` result is free, so retrying it costs nothing until the server gives a real answer. Wait at least `retry_after` seconds, then verify again. - **Signup forms:** accept the address, then re-check it in the background before the first important email. - **Lists:** keep unknown rows in a separate segment and re-verify them in a later job. The [list cleaning guide](https://docs.rocketverifier.com/guides/list-cleaning) shows the full loop. - **`blocked`:** the mail server rejects verification probes by policy. Retrying later often succeeds; repeated `blocked` results on one domain mean that server never answers probes. ## What is charged Each verification costs 1 credit, except where it cost us no verification work or gave no answer. | Result | Cost | | --- | --- | | `deliverable`, `undeliverable`, `risky` | 1 credit | | Catch-all, in either result version | 1 credit | | `unknown` (every transient sub status, `possible_typo` reported as unknown) | Free | | Address on your own suppression list (`do_not_mail`) | Free | | Sandbox addresses at `@sandbox.rocketverifier.com` | Free | | Retry with the same `Idempotency-Key` within 24 hours | Free (the stored result is returned) | | Duplicate addresses inside one bulk job | Free (each unique address is charged once) | Bulk jobs are charged 1 credit per unique address up front, and unknown results are refunded when the job completes. ## Decide by use case The right action depends on where the address came from. At signup, a person is typing and can fix a mistake right now. In a list, nobody is there to ask, so you protect your sender reputation. | Result | Signup form | List cleaning | | --- | --- | --- | | `deliverable` | Accept | Keep | | `undeliverable` with `did_you_mean` | Block and show the suggestion | Remove, or fix it if you can confirm with the contact | | `undeliverable` (any other) | Block: "This address can't receive email" | Remove | | `disposable` | Block: ask for a permanent address | Remove | | `risky` + `role_based` | Accept | Keep for B2B and transactional mail | | `risky` + `catch_all` | Accept unless `catch_all_verdict` is `avoid` | Keep `send_safe`, segment `send_with_caution`, remove `avoid` | | `risky` + `possible_typo` | Warn and show `did_you_mean` | Review | | `risky` + `mailbox_full` | Accept | Suppress for now, re-verify later | | `risky` + `possible_trap`, `toxic`, `do_not_mail` | Block | Remove | | `risky` + `accepts_then_bounces`, `parked_domain` | Warn | Remove | | `risky` + `privacy_relay` | Accept | Keep | | `unknown` | Accept and re-check in the background | Hold in a segment and re-verify | ## Branch on results in code This function turns a result into one of three actions. It reads the raw API fields, so it works with any HTTP client. The SDKs expose the same fields in their own casing (`subStatus` and `didYouMean` in Node.js). Node.js: ```js const BLOCK = new Set(["possible_trap", "toxic", "do_not_mail", "disposable"]); const WARN = new Set(["possible_typo", "accepts_then_bounces", "parked_domain"]); export async function verify(email) { const res = await fetch("https://api.rocketverifier.com/v1/verify", { method: "POST", headers: { Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`, "Content-Type": "application/json", "RocketVerifier-Version": "2026-11-01", }, body: JSON.stringify({ email }), }); if (!res.ok) throw new Error(`RocketVerifier ${res.status}`); return res.json(); } export function decide(r) { if (r.status === "deliverable") return { action: "accept" }; if (r.status === "unknown") return { action: "accept", retryInSeconds: r.retry_after ?? 300 }; if (r.status === "undeliverable" || BLOCK.has(r.sub_status)) { return { action: "block", suggestion: r.did_you_mean }; } if (r.sub_status === "catch_all" && r.catch_all_verdict === "avoid") return { action: "block" }; if (WARN.has(r.sub_status)) return { action: "warn", suggestion: r.did_you_mean }; return { action: "accept", flag: r.sub_status }; // role_based, catch_all, mailbox_full, privacy_relay } const result = await verify("maya@northwind.io"); console.log(decide(result)); ``` Python: ```python import os import requests BLOCK = {"possible_trap", "toxic", "do_not_mail", "disposable"} WARN = {"possible_typo", "accepts_then_bounces", "parked_domain"} def verify(email: str) -> dict: res = requests.post( "https://api.rocketverifier.com/v1/verify", headers={ "Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}", "RocketVerifier-Version": "2026-11-01", }, json={"email": email}, timeout=35, ) res.raise_for_status() return res.json() def decide(r: dict) -> dict: if r["status"] == "deliverable": return {"action": "accept"} if r["status"] == "unknown": return {"action": "accept", "retry_in_seconds": r.get("retry_after") or 300} if r["status"] == "undeliverable" or r["sub_status"] in BLOCK: return {"action": "block", "suggestion": r.get("did_you_mean")} if r["sub_status"] == "catch_all" and r.get("catch_all_verdict") == "avoid": return {"action": "block"} if r["sub_status"] in WARN: return {"action": "warn", "suggestion": r.get("did_you_mean")} return {"action": "accept", "flag": r["sub_status"]} # role_based, catch_all, mailbox_full, privacy_relay print(decide(verify("maya@northwind.io"))) ``` ## Results in bulk jobs Bulk job rows use the same vocabulary. [`GET /v1/jobs/{id}/results`](https://docs.rocketverifier.com/api/batch) returns `status`, `sub_status`, `confidence_score` (the score), `is_catch_all` and `verified_at` for each address, and honours the `RocketVerifier-Version` header. Downloads add `did_you_mean`, `catch_all_verdict`, `catch_all_score` and the other detail columns, and can be filtered to one segment such as `deliverable` or `send_safe`. ## Next steps - [Catch-all domains](https://docs.rocketverifier.com/catch-all) How the catch-all verdict is reached and what to send to. - [Result versions](https://docs.rocketverifier.com/versioning) Pick how catch-all results map onto status with one header. - [Verify at signup](https://docs.rocketverifier.com/guides/signup-verification) Block bad addresses on your forms with a server-side check or RocketShield. - [Clean a list](https://docs.rocketverifier.com/guides/list-cleaning) Upload, preview for free, verify and download clean segments. ## Frequently asked questions ### Am I charged for unknown results? No. An unknown result means the mail server gave no conclusive answer, so it costs nothing. Retry after the number of seconds in retry_after. Addresses on your own suppression list are also free. ### Is a risky address safe to send to? It accepts mail but carries a specific risk, named in sub_status. Role addresses and catch-all addresses with a send_safe verdict are usually fine for opted-in mail. Drop possible_trap, toxic and do_not_mail addresses from every send. ### What does a score of 80 mean? For addresses that reach the mailbox check, the score is a calibrated probability. A score of 80 means about 80 percent of addresses with the same signals delivered. It is capped at 10 for rejected mailboxes and 60 for unknown results. Branch on status first and use the score to rank within a status. ### Why is verified_at earlier than my request? Results are cached for 6 hours (5 minutes for transient unknowns), so a repeat check returns the cached verdict in milliseconds. verified_at shows when the verdict was produced and verdict_source is cache. ### Should I auto-correct addresses with a did_you_mean suggestion? No. Show the suggestion to the person and let them confirm it. did_you_mean holds a full corrected address, for example maya@gmail.com for maya@gmial.com. --- # Catch-all domains Source: https://docs.rocketverifier.com/catch-all > A catch-all domain accepts mail for every address, so a plain SMTP check cannot tell a real mailbox from a made-up one. RocketVerifier scores each address on the domain from 0 to 100 and returns a catch_all_verdict of send_safe, send_with_caution or avoid. Catch-all results cost 1 credit and report status risky under result version 2026-11-01. A catch-all (or accept-all) domain tells the mail server to accept every recipient, real or not. Any verifier that stops at the SMTP handshake can only say "this domain accepts everything". RocketVerifier goes further and decides, address by address, which ones are worth sending to. ## How a catch-all domain is detected During the SMTP conversation, RocketVerifier also asks the server about a random address on the same domain, a 14 character string that no real mailbox uses. If the server accepts it, the domain is catch-all. The probe result is cached per domain for 7 days, so later addresses on the domain skip it. Two outcomes are worth knowing: - **Accepted, probe inconclusive.** When the server accepts the address but blocks or times out the random-address probe, an accept-all domain cannot be ruled out. The result is `unknown`, and free. - **Rejected on a catch-all domain.** When a domain that accepts nearly everything explicitly rejects this address, the result is `undeliverable` with `mailbox_not_found`. ## How the verdict is reached The Catch-All Resolution Engine turns the signals below into a 0 to 100 resolution score for the specific address. 1. **Local part plausibility.** Does the part before the `@` look like a real person's name (`maya.patel`, `mpatel`) or a generated string (`xk29fj2`)? This is the starting point. 2. **The domain's naming pattern.** RocketVerifier learns which naming convention a domain uses (`first.last`, first initial plus last name, and so on) from mailboxes confirmed while the domain still answered per mailbox. An address that matches the convention scores higher; one that breaks it scores lower. The weight grows with how many confirmed mailboxes back the pattern and how consistently the domain uses it. 3. **Mail provider.** A catch-all on a well-run mail platform gets a small boost over one on an unknown, self-hosted server. 4. **Bounce feedback.** Hard bounces from connected sending platforms show how often addresses on the domain, and of each naming shape, bounce after being accepted. 5. **Verification history.** A definitive answer for this exact address, from a check made while the domain still answered per mailbox, overrides the estimate: a confirmed mailbox scores at least 88, a confirmed rejection or a later hard bounce at most 10. The pattern store holds counts of naming shapes per domain, never addresses, and keeps them for 180 days. Bounce feedback and verification history are stored as domain aggregates and keyed hashes, and only accounts that share in the data network use them. You can turn that off under **Settings → Privacy**. The score maps to a verdict: | catch_all_verdict | Meaning | | --- | --- | | `send_safe` | Resolution score 65 or higher: strong signals this mailbox is real and active. | | `send_with_caution` | Resolution score 35 to 64, or too little evidence to decide. Send to engaged segments or warm the address first. | | `avoid` | Resolution score below 35: signals point to a mailbox that does not exist. | ## Read the catch-all fields A catch-all result carries the verdict in three places, so every integration finds it: Catch-all result (excerpt): ```json { "email": "maya.patel@lakeside-dental.com", "status": "risky", "sub_status": "catch_all", "catch_all_verdict": "send_safe", "catch_all": { "verdict": "send_safe", "score": 82, "method": "pattern", "reasons": [ "Local part looks like a real name (e.g. first.last)", "Matches this domain's known naming pattern (first.last, seen in 92% of 25 verified mailboxes)" ] }, "domain": { "name": "lakeside-dental.com", "acceptAll": "yes", "disposable": "no", "free": "no" } } ``` - `catch_all_verdict` is the recommendation. It is `null` on every domain that is not catch-all. - `catch_all.score` is the resolution score behind it. `method` is `pattern` when the address matched the domain's learned naming convention and `heuristic` otherwise. `reasons` lists up to five plain-language explanations you can show in your own interface. - `domain.acceptAll` is `"yes"` on catch-all domains. `sub_status` is `catch_all` for these addresses, unless a stronger reason applies first, such as `possible_trap`, `toxic` or `do_not_mail`. ## Act on each verdict Treat the verdict as a sending decision, and match it to how much risk the mail can take. | Verdict | Signup form | Marketing list | Cold outreach | | --- | --- | --- | --- | | `send_safe` | Accept | Keep | Send | | `send_with_caution` | Accept | Send to engaged contacts first, watch bounces | Hold, or send in small batches | | `avoid` | Ask for another address | Remove | Remove | For bulk jobs, download the `send_safe` segment: every `deliverable` address plus catch-all addresses with a score of 65 or higher, with disposable and role addresses left out. cURL: ```bash curl "https://api.rocketverifier.com/v1/jobs/$JOB_ID/download?filter=send_safe" \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -o send-safe.csv ``` Connect SendGrid, Mailgun or Postmark to feed real bounces back into the score. Hard bounces sharpen the verdicts for the domains you mail, and go straight onto your suppression list. See the [Bounce Guarantee](https://docs.rocketverifier.com/integrations/bounce-guarantee). ## How result versions change the status The verdict is the same in every version; only the `status` label changes. | Result version | `status` of a catch-all address | Charged | | --- | --- | --- | | `2026-11-01` (current) | `risky` | 1 credit | | `2025-01-01` (legacy) | `unknown` | 1 credit | Under `2025-01-01`, a catch-all address shares the `unknown` status with transient failures, but unlike them it is charged and carries a verdict. Read `sub_status` or `domain.acceptAll` to tell them apart, or send `RocketVerifier-Version: 2026-11-01`. A role address on a catch-all domain is `risky` in both versions. The [result versions page](https://docs.rocketverifier.com/versioning) covers the header and key defaults. ## Next steps - [Reading results](https://docs.rocketverifier.com/results) Every status and sub_status, what it costs and what to do with it. - [Clean a list](https://docs.rocketverifier.com/guides/list-cleaning) Download send-safe segments from a bulk job. ## Frequently asked questions ### Are catch-all results charged? Yes, 1 credit, because the domain gave a real answer and every catch-all result carries a per-address verdict. This applies under both result versions, including 2025-01-01 where the status reads unknown. ### Why is a catch-all address risky and not deliverable? The server accepts every recipient, so its answer says nothing about the specific mailbox. Only the resolution score separates real mailboxes from guesses, so the status stays risky and the verdict tells you what to do. ### Which catch-all addresses are safe to send to? Addresses with catch_all_verdict send_safe, which needs a resolution score of 65 or higher. Download a job with filter=send_safe to get every deliverable address plus the catch-all addresses that score 65 or more, without disposable or role addresses. ### How do I find the catch-all addresses in an old integration that reads status? Read domain.acceptAll, which is "yes" on catch-all domains in every result version, or sub_status, which is catch_all. Under result version 2025-01-01 these addresses report status unknown even though they were charged. --- # Result versions Source: https://docs.rocketverifier.com/versioning > The RocketVerifier-Version header picks how results map onto status. 2026-11-01, the current version, reports catch-all addresses as risky; 2025-01-01 reports them as unknown. Everything else is identical. API keys created from November 2026 default to 2026-11-01, and a valid header always wins. The public `status` vocabulary (`deliverable`, `undeliverable`, `risky`, `unknown`) is stable. How one kind of result maps onto it changed once, in November 2026, and the result version lets each integration choose the mapping it was built for. ## What differs between versions Only catch-all addresses change. Every other field, value and charge is the same in both versions. | Result | `2025-01-01` (legacy) | `2026-11-01` (current) | | --- | --- | --- | | Mailbox confirmed | `deliverable` | `deliverable` | | Mailbox rejected, bad syntax or domain, disposable | `undeliverable` | `undeliverable` | | Risk signal (role, full mailbox, trap, toxic, typo and others) | `risky` | `risky` | | Catch-all domain | `unknown` | `risky` | | No conclusive answer | `unknown` | `unknown` | Under `2026-11-01`, `unknown` always means "no answer yet, free, retry later". Under `2025-01-01`, `unknown` mixes those free results with catch-all addresses, which are charged and carry a [catch-all verdict](https://docs.rocketverifier.com/catch-all). The current version keeps the two apart, so `status` alone tells you whether a retry makes sense. ## Pick a version with the header Send `RocketVerifier-Version` with `2026-11-01` or `2025-01-01` on any request. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -H "RocketVerifier-Version: 2026-11-01" \ -d '{"email": "maya.patel@lakeside-dental.com"}' ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; // Extra headers are sent with every request this client makes. const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY, { headers: { "RocketVerifier-Version": "2026-11-01" }, }); const result = await rv.verify("maya.patel@lakeside-dental.com"); ``` Python: ```python import os import requests res = requests.post( "https://api.rocketverifier.com/v1/verify", headers={ "Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}", "RocketVerifier-Version": "2026-11-01", }, json={"email": "maya.patel@lakeside-dental.com"}, timeout=35, ) print(res.json()["status"]) # "risky" for a catch-all address ``` The header applies to every endpoint that returns a public status: - `POST /v1/verify` - `GET /v1/jobs/{id}/results` - `GET /v1/jobs/{id}/download`, including the `filter=risky` and `filter=unknown` segments - The `email.verified` webhook payload of a real-time check, which carries the status that request returned ## Defaults when no header is sent The effective version is chosen in this order: a valid header, then the credential's own version, then `2025-01-01`. | Credential | Default version | | --- | --- | | API key created from November 2026 | `2026-11-01` | | API key created before November 2026 | `2025-01-01` | | Organization API key | `2025-01-01` | | OAuth access token (`rv_at_`) | `2025-01-01` | | Dashboard | `2026-11-01`, always | A key's version is fixed when the key is created. To move a key to the current mapping, send the header, or create a new key in the [dashboard](https://app.rocketverifier.com/dashboard/api-keys) and swap it in. ## Migrate to 2026-11-01 Migration takes one header and one review of code that handles `unknown`. **Step 1. Find code that treats unknown as catch-all** Search for places that read `status === "unknown"` and then check `domain.acceptAll`, `reason === "catch_all"` or `catch_all_verdict`. Under the current version those addresses arrive as `risky` with `sub_status: "catch_all"`. **Step 2. Move catch-all handling to the risky branch** Read `catch_all_verdict` inside your `risky` branch: send `send_safe`, segment `send_with_caution`, drop `avoid`. Your `unknown` branch now only ever sees free results to retry after `retry_after` seconds. **Step 3. Send the header everywhere** Add `RocketVerifier-Version: 2026-11-01` to every request, including job result reads and downloads, so live checks and stored results use the same mapping. **Step 4. Check dashboards and reports** Counts by `status` shift: catch-all addresses move from `unknown` to `risky`. Job counters such as `catch_all_count` in `GET /v1/jobs/{id}` and the `job.completed` webhook are reported separately and do not change. Pinning the header is also the safest way to keep an integration stable: your results stay on the version you tested against, whatever key runs them. ## Next steps - [Reading results](https://docs.rocketverifier.com/results) Every status and sub_status, what it costs and what to do with it. - [Catch-all domains](https://docs.rocketverifier.com/catch-all) How the catch-all verdict is reached and what to send to. ## Frequently asked questions ### Which version should I use? 2026-11-01. It reports catch-all addresses as risky, which keeps unknown for results that are free and worth retrying. New integrations should send the header on every request. ### Does the version change what I am charged? No. Catch-all results cost 1 credit in both versions, and unknown results are free in both. The version changes only the status label of catch-all addresses. ### What happens if I send an unsupported version? The header is ignored and the key's version applies, or 2025-01-01 when the key has none. Check the value for typos if results do not change. ### Which version does the dashboard use? The dashboard always shows results with the current version, 2026-11-01. --- # Bounce Guarantee Source: https://docs.rocketverifier.com/integrations/bounce-guarantee > Connect SendGrid, Mailgun or Postmark and every confirmed hard bounce of an address a job marked deliverable within the previous 30 days is refunded automatically, 1 credit per verification, and the address is suppressed. Without a connected platform, file a claim from the job page within 30 days and get 1 credit back for every hard bounce above 4% of the job's deliverable addresses. RocketVerifier puts credits behind every deliverable result. When an address a job marked deliverable hard-bounces, you get the credit for that verification back, automatically when your sending platform is connected. ## Automatic refunds Connect the platform you send through, and RocketVerifier watches its bounce feed. Every confirmed hard bounce of a deliverable result comes back as a credit, with no claim to file. **Step 1. Verify a list** Verify the list in a bulk job, a file upload, a dashboard list or an integration sync. Each address costs 1 credit. **Step 2. Send to the deliverable addresses** Send through [SendGrid](https://docs.rocketverifier.com/integrations/sendgrid), [Mailgun](https://docs.rocketverifier.com/integrations/mailgun) or [Postmark](https://docs.rocketverifier.com/integrations/postmark), connected in **Dashboard → Integrations**. **Step 3. A hard bounce is reported** The platform reports the bounce through its signed webhook, and RocketVerifier also reads its bounce feed once a day. The bounce is confirmed with the platform's own API before any refund. **Step 4. Credit back and suppression** 1 credit returns to your balance, shown in the credit history as "Bounce guarantee refund", and the address goes onto your suppression list. ### What is refunded - A **hard bounce**, a permanent delivery failure, confirmed by the connected platform. - Of an address that a **charged verification on your account** returned as `deliverable`. - Within the **30 days before the bounce**. The most recent matching verification is the one refunded. - **1 credit, once per verification.** Gmail-style variants of an address (dots and `+tags`) are matched to the verification they belong to. ### What is not refunded - Soft bounces, such as a full mailbox or a temporary server error. They are recorded only. - Spam complaints. They go onto your suppression list, without a refund. - Addresses returned as `risky` (including catch-all), `unknown` or `undeliverable`. - Verifications older than 30 days when the bounce happens. - Single `POST /v1/verify` calls. Only job verifications are covered. - Jobs run with a sandbox key, which were never charged. - A verification that was already refunded. ## Automatic suppression Hard bounces and complaints from every connected platform, Amazon SES included, go onto an automatically managed suppression list called **Bounces & complaints (auto)**, created on the first event. Every later check of those addresses, in the API, uploads and syncs, returns `risky` with `sub_status: "do_not_mail"` and costs nothing. The free list health preview counts them as suppressed. ## Supported platforms | Platform | Bounce feed | Automatic refunds | | --- | --- | --- | | [SendGrid](https://docs.rocketverifier.com/integrations/sendgrid) | Signed Event Webhook, plus a daily poll | Yes | | [Mailgun](https://docs.rocketverifier.com/integrations/mailgun) | Signed webhooks, plus a daily poll | Yes | | [Postmark](https://docs.rocketverifier.com/integrations/postmark) | Webhook, plus a daily poll | Yes | | [Amazon SES](https://docs.rocketverifier.com/integrations/ses) | SNS notifications | Suppression only; claim refunds from the job page | Each integration has its own webhook URL, shown on its page in the dashboard: Bounce webhook URL: ```text https://api.rocketverifier.com/webhooks/connectors/{platform}/{integration_id} ``` Deliveries are checked against each platform's own signature or authentication scheme, and events that fail the check are rejected. Refunds apply to verifications on the same RocketVerifier account that connected the platform. ## Claim a refund from the job page Not connected? File a claim. If more than 4% of a job's deliverable addresses hard-bounce within 30 days, you get 1 credit back for every hard bounce above 4%. **Step 1. Send to the deliverable addresses** Send your campaign to the addresses the job marked deliverable, and note the hard bounces your sending platform reports. **Step 2. Open the job** Open the completed job in the [dashboard](https://app.rocketverifier.com/dashboard/jobs) within 30 days of its completion, and choose **Claim bounce guarantee**. **Step 3. Enter the bounce count** Enter how many of the job's deliverable addresses hard-bounced. The claim is decided on the spot. ### How a claim is calculated The bounce rate is the number of hard bounces divided by the number of addresses the job marked deliverable. Above 4%, every bounce over the threshold comes back as a credit. | | Example | | --- | --- | | Addresses marked deliverable | 10,000 | | Hard bounces within 30 days | 460 | | 4% threshold | 400 | | **Credits returned** | **60** | A bounce rate of 4% or less is within the threshold, which covers the normal churn of mailboxes closing between verification and sending. Each job takes one claim. ### Claims do not cover - Addresses returned as risky, catch-all or unknown. - Soft bounces, such as a full mailbox or a temporary server error. - Bounces caused by your sending reputation, content or authentication setup. - Claims filed more than 30 days after the job completed. ## Next steps - [SendGrid](https://docs.rocketverifier.com/integrations/sendgrid) Connect SendGrid's Event Webhook for automatic refunds. - [Reading results](https://docs.rocketverifier.com/results) What deliverable means and what every status costs. ## Frequently asked questions ### Is the Bounce Guarantee a cash refund? No. It returns credits to your balance, and credits never expire. Credit purchases themselves are final. ### Which results are covered? Addresses a bulk job, file upload, dashboard list or integration sync returned as deliverable. Risky, catch-all, unknown and undeliverable results are not covered, and neither are single POST /v1/verify calls. ### Does Amazon SES give automatic refunds? SES bounces and complaints go onto your suppression list, but SES has no API to confirm a bounce, so SES senders claim refunds from the job page. SendGrid, Mailgun and Postmark bounces are confirmed with the provider and refunded automatically. ### Can one bounce be refunded twice? No. Each verification is refunded at most once, however many times or through however many channels the bounce arrives. Webhook retries and overlapping polls are recognised and ignored. --- # Verify emails at signup Source: https://docs.rocketverifier.com/guides/signup-verification > Check every new address before you create the account. Drop in the RocketShield script for instant feedback with no backend code, and call POST /v1/verify from your server with a 5 second timeout to enforce the decision. Block undeliverable, disposable and toxic addresses, offer did_you_mean for typos, and accept unknown results so a slow mail server never stops a real signup. A fake or mistyped address at signup costs you twice: the person never gets your welcome email, and every later bounce hurts your sender reputation. Checking the address while the person is still on the page fixes both. ## Pick an approach Use RocketShield for instant feedback in the browser, the server-side check to enforce the rule, or both together. | | RocketShield widget | Server-side `POST /v1/verify` | | --- | --- | --- | | Where it runs | In the browser, on your form | On your server, before you create the account | | Setup | Paste one script tag | One HTTP call in your signup handler | | Credential | Public `rs_` key, locked to your domains | Secret API key, never in the browser | | Feedback | As the person types, under the field | On submit, from your own error message | | Stops bots posting directly to your backend | No | Yes | | Best for | No-code sites, WordPress, Shopify, Webflow | Apps with their own signup endpoint | The strongest setup uses both: RocketShield helps people fix mistakes before they submit, and the server check enforces the decision for every request that reaches your backend. ## Add RocketShield Create a shield in the dashboard under **RocketShield**, add the domains it runs on, and paste the embed code before ``: HTML: ```html ``` RocketShield finds the email fields on the page, verifies as the person types and blocks the submit for the result types you choose in the shield's settings, such as disposable, undeliverable or toxic addresses. The [RocketShield guide](https://docs.rocketverifier.com/integrations/widget) covers every option, styling and platform plugins, including [WordPress](https://docs.rocketverifier.com/integrations/wordpress). ## Set a latency budget A signup check has to be fast, and it has to give up gracefully. Plan for these times: | Path | Typical time | | --- | --- | | Decided by syntax, DNS, list checks or cache | Under 400 ms | | Live SMTP mailbox check | 1 to 3 seconds | | Your ceiling, with `timeout: 5` | 5 seconds | Send `timeout` in the request body, in seconds (3 to 60, default 10, capped at 30). When the mail server has not answered by then, the API returns `unknown`, which is free, and you accept the signup. Give your own HTTP client a few seconds more than `timeout`, so the API always answers first. ## Decide what to block and what to warn Block only what is certainly wrong or harmful, warn when the person can fix it, and accept everything else. Accepting an `unknown` result is always right at signup: the person is real until proven otherwise. | Result | Action | Message to show | | --- | --- | --- | | `deliverable` | Accept | | | `undeliverable` with `did_you_mean` | Block | "Did you mean maya@gmail.com?" | | `undeliverable` (any other) | Block | "This address can't receive email. Please check it." | | `disposable` | Block | "Please use a permanent email address." | | `risky` + `toxic`, `possible_trap`, `do_not_mail` | Block | "Please use a different email address." | | `risky` + `possible_typo` | Warn, let them continue | "Did you mean maya@gmail.com?" | | `risky` + `catch_all` with `catch_all_verdict: "avoid"` | Warn | "Please double-check this address." | | `risky` (any other) | Accept | | | `unknown` | Accept, re-check later | | [Reading results](https://docs.rocketverifier.com/results) explains every `sub_status` behind these rules. ## Offer typo suggestions `did_you_mean` holds a full corrected address, such as `maya@gmail.com` for `maya@gmial.com`. Show it as a one-click fix, and let the person decide. - Never rewrite the address silently: the suggestion fixes the domain, and only the person knows their mailbox. - After they accept the suggestion, verify the new address too. - On a `possible_typo` warning, let them keep the original. Some typo-like domains are real. ## Protect the check from abuse A public signup form is an open door. Keep the verification behind it cheap and safe: - **Check on submit, not on every keystroke,** and only after a basic syntax check in your own code. - **Rate limit your signup endpoint** per IP address, and put a captcha in front of it if bots find it. - **Send an `Idempotency-Key`** derived from the address and the day. Repeat submissions of the same address return the stored result for 24 hours and are not charged again. - **Give the signup service its own key** with only the `verify:single` scope, a monthly credit limit and, on servers with fixed addresses, an IP allowlist. A runaway loop stops at the cap. See [authentication](https://docs.rocketverifier.com/authentication). - **Let the verdict catch bots.** `toxic` flags machine-generated local parts, and `do_not_mail` flags known complainers. ## Full server example This handler verifies the address with a 5 second budget, applies the table above, and fails open when the API cannot answer. Node.js: ```js // npm install express import crypto from "node:crypto"; import express from "express"; const app = express(); app.use(express.json()); const BLOCK = new Set(["disposable", "toxic", "possible_trap", "do_not_mail"]); const MESSAGES = { disposable: "Please use a permanent email address.", default: "This address can't receive email. Please check it.", abuse: "Please use a different email address.", }; async function verifyEmail(email) { const day = new Date().toISOString().slice(0, 10); const idempotencyKey = crypto.createHash("sha256").update(`${email}:${day}`).digest("hex"); try { const res = await fetch("https://api.rocketverifier.com/v1/verify", { method: "POST", headers: { Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, "RocketVerifier-Version": "2026-11-01", }, body: JSON.stringify({ email, timeout: 5 }), signal: AbortSignal.timeout(8000), }); if (!res.ok) return null; // 4xx/5xx: fail open return await res.json(); } catch { return null; // network error or timeout: fail open } } function decide(r) { if (!r || r.status === "unknown") return { action: "accept", recheck: true }; if (r.status === "deliverable") return { action: "accept" }; if (r.did_you_mean && r.status === "undeliverable") { return { action: "block", message: `Did you mean ${r.did_you_mean}?`, suggestion: r.did_you_mean }; } if (r.sub_status === "disposable") return { action: "block", message: MESSAGES.disposable }; if (r.status === "undeliverable") return { action: "block", message: MESSAGES.default }; if (BLOCK.has(r.sub_status)) return { action: "block", message: MESSAGES.abuse }; if (r.sub_status === "possible_typo") { return { action: "warn", message: `Did you mean ${r.did_you_mean}?`, suggestion: r.did_you_mean }; } if (r.sub_status === "catch_all" && r.catch_all_verdict === "avoid") { return { action: "warn", message: "Please double-check this address." }; } return { action: "accept" }; } app.post("/signup", async (req, res) => { const email = String(req.body.email ?? "").trim().toLowerCase(); if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) { return res.status(422).json({ error: "Enter a valid email address." }); } const decision = decide(await verifyEmail(email)); if (decision.action === "block") { return res.status(422).json({ error: decision.message, suggestion: decision.suggestion }); } if (decision.action === "warn" && !req.body.confirmed) { return res.status(409).json({ warning: decision.message, suggestion: decision.suggestion }); } const user = await createUser({ email, password: req.body.password }); if (decision.recheck) await queueRecheck(user.id, email); return res.status(201).json({ id: user.id }); }); app.listen(3000); ``` Python: ```python # pip install flask rocketverifier import hashlib import os import re from datetime import date from flask import Flask, jsonify, request from rocketverifier import RocketVerifier, RocketVerifierError app = Flask(__name__) rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"], timeout=10, max_retries=0) BLOCK = {"disposable", "toxic", "possible_trap", "do_not_mail"} EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$") def verify_email(email: str): key = hashlib.sha256(f"{email}:{date.today().isoformat()}".encode()).hexdigest() try: return rv.verify(email, idempotency_key=key, timeout=5) except RocketVerifierError: return None # network error, rate limit, credits or server error: fail open def decide(r) -> dict: if r is None or r.status == "unknown": return {"action": "accept", "recheck": True} if r.status == "deliverable": return {"action": "accept"} if r.did_you_mean and r.status == "undeliverable": return {"action": "block", "message": f"Did you mean {r.did_you_mean}?", "suggestion": r.did_you_mean} if r.sub_status == "disposable": return {"action": "block", "message": "Please use a permanent email address."} if r.status == "undeliverable": return {"action": "block", "message": "This address can't receive email. Please check it."} if r.sub_status in BLOCK: return {"action": "block", "message": "Please use a different email address."} if r.sub_status == "possible_typo": return {"action": "warn", "message": f"Did you mean {r.did_you_mean}?", "suggestion": r.did_you_mean} if r.sub_status == "catch_all" and r.catch_all_verdict == "avoid": return {"action": "warn", "message": "Please double-check this address."} return {"action": "accept"} @app.post("/signup") def signup(): body = request.get_json(force=True) email = str(body.get("email", "")).strip().lower() if not EMAIL_RE.match(email): return jsonify(error="Enter a valid email address."), 422 decision = decide(verify_email(email)) if decision["action"] == "block": return jsonify(error=decision["message"], suggestion=decision.get("suggestion")), 422 if decision["action"] == "warn" and not body.get("confirmed"): return jsonify(warning=decision["message"], suggestion=decision.get("suggestion")), 409 user = create_user(email=email, password=body.get("password")) if decision.get("recheck"): queue_recheck(user.id, email) return jsonify(id=user.id), 201 ``` `createUser` and `queueRecheck` (`create_user` and `queue_recheck`) are your own functions. The re-check job verifies the address again after its `retry_after` seconds, before you send anything important. ## Test the flow Point the handler at [sandbox addresses](https://docs.rocketverifier.com/sandbox) with an `rv_test_` key to exercise every branch for free: | Address | Expected action | | --- | --- | | `deliverable@sandbox.rocketverifier.com` | Accept | | `undeliverable@sandbox.rocketverifier.com` | Block | | `disposable@sandbox.rocketverifier.com` | Block, permanent address message | | `admin@sandbox.rocketverifier.com` | Accept (role address) | | `risky@sandbox.rocketverifier.com` | Accept (catch-all, `send_with_caution`) | | `unknown@sandbox.rocketverifier.com` | Accept and queue a re-check | ## Next steps - [RocketShield](https://docs.rocketverifier.com/integrations/widget) Every widget option, styling and platform plugin. - [Reading results](https://docs.rocketverifier.com/results) What every status and sub_status means and costs. - [Verify endpoint](https://docs.rocketverifier.com/api/verify) Request fields, response fields and errors. - [Rate limits](https://docs.rocketverifier.com/rate-limits) How many signups per minute your plan handles. ## Frequently asked questions ### Will verification slow down my signup form? Most answers return in under 400 milliseconds because they are decided by syntax, DNS, list checks or cache. A live mailbox check typically takes 1 to 3 seconds. Set timeout to 5 and the request never takes longer; a timeout returns unknown, which is free. ### Should I block role addresses like info@ at signup? For B2B products, usually not, because teams sign up with shared inboxes. Block them only when every account must belong to one person. RocketShield and the decision table on this page treat them as accept by default. ### What if RocketVerifier is unreachable? Accept the signup and queue a re-check. The example on this page fails open on network errors, rate limits and server errors, so an outage never blocks a real customer. ### Is RocketShield enough on its own? For instant feedback, yes. To enforce the rule against bots that post to your signup endpoint directly, add the server-side check as well. The two work together. ### How much does signup verification cost? 1 credit per checked address, except unknown results and addresses on your suppression list, which are free. Repeat submissions of the same address within 24 hours are free when you send the same Idempotency-Key. --- # Clean an email list Source: https://docs.rocketverifier.com/guides/list-cleaning > Upload the file with preview=true and read the free list health preview, which estimates the bounce rate and the credits needed before you spend anything. Confirm to verify every unique address for 1 credit each, get a job.completed webhook, then download the send_safe, risky and unknown segments. Re-verify anything older than 30 days before you mail it, and let a monitor watch the list in between. A list cleaning run has five steps: upload, preview, confirm, wait, download. The free preview comes first, so you know the list's health and the cost before a single credit is spent. ## Upload the file Send the file to [`POST /v1/verify/bulk/upload`](https://docs.rocketverifier.com/api/bulk-upload) with `preview=true`. The API accepts CSV, TSV, TXT and XLSX files up to 50 MB and 500,000 unique addresses, or a public HTTPS `source_url` it fetches for you. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify/bulk/upload \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -F "file=@contacts.csv" \ -F "name=Q4 newsletter list" \ -F "email_column=Work Email" \ -F "preview=true" ``` Node.js: ```js import { readFile } from "node:fs/promises"; import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); const upload = await rv.batch.upload({ file: await readFile("contacts.csv"), filename: "contacts.csv", name: "Q4 newsletter list", emailColumn: "Work Email", preview: true, }); console.log(upload.jobId, upload.status); // "ingesting" ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) upload = rv.batch.upload( "contacts.csv", name="Q4 newsletter list", email_column="Work Email", preview=True, ) print(upload.job_id, upload.status) # "ingesting" ``` The email column is found automatically when you leave out `email_column`. Every other column is kept, so the download can return your original data next to the results. Prefer the dashboard? **Bulk verify** runs the same flow with a drag and drop upload. ## Read the free preview The preview runs on every row and costs nothing: syntax, disposable domains, role addresses, MX records, duplicates and your suppression lists, plus a live mailbox check on a random sample (2% of the list, at most 200 addresses). Poll [`POST /v1/verify/bulk/{id}/preview`](https://docs.rocketverifier.com/api/bulk-upload) until it is ready. Node.js: ```js let result = await rv.batch.preview(upload.jobId); while (result.pending) { await new Promise((r) => setTimeout(r, 3000)); result = await rv.batch.preview(upload.jobId); } const p = result.preview; console.log(`Estimated bounce rate: ${(p.estimatedBounceRate * 100).toFixed(1)}%`); console.log(`Credits on confirm: ${p.creditsNeeded}, after unknown refunds: ${p.estimatedCreditsAfterRefunds}`); ``` Python: ```python import time result = rv.batch.preview(upload.job_id) while result.pending: time.sleep(3) result = rv.batch.preview(upload.job_id) p = result.preview print(f"Estimated bounce rate: {p.estimated_bounce_rate:.1%}") print(f"Credits on confirm: {p.credits_needed}, after unknown refunds: {p.estimated_credits_after_refunds}") ``` | Preview field | Meaning | | --- | --- | | `estimated_bounce_rate` | Share of the list (0 to 1) expected to hard-bounce if you mailed it today | | `risky_share`, `unknown_share` | Expected share of risky and unknown results | | `credits_needed` | Credits charged on confirm: 1 per unique address | | `estimated_credits_after_refunds` | Expected net cost once unknown results are refunded | | `free_checks` | Counts from the per-row checks, such as invalid syntax, no MX, disposable and role addresses | | `confidence` | `high`, `medium` or `low`, from the sample size | A list with a high estimated bounce rate is exactly the list to verify before you send. A list that comes back clean and recently verified can wait. ## Confirm the job Confirming charges 1 credit per unique address and starts verification. It is safe to retry: a job is never charged twice. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify/bulk/$JOB_ID/confirm \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const confirmed = await rv.batch.confirm(upload.jobId); console.log(confirmed.creditsCharged, confirmed.creditsRemaining); ``` Python: ```python confirmed = rv.batch.confirm(upload.job_id) print(confirmed.credits_charged, confirmed.credits_remaining) ``` Unknown results are refunded when the job completes, so the final cost is usually lower than the amount charged on confirm. Uploads without `preview=true` are charged and started as soon as the file is read. ## Get notified when it finishes Register a webhook once, and every finished job sends a signed `job.completed` event with the counts and a `download_url`. Bulk jobs run at up to 100,000 emails per hour. Node.js: ```js const webhook = await rv.webhooks.create({ url: "https://example.com/hooks/rocketverifier", events: ["job.completed", "job.failed"], }); console.log(webhook.secret); // store it to verify signatures ``` Python: ```python webhook = rv.webhooks.create( "https://example.com/hooks/rocketverifier", events=["job.completed", "job.failed"], ) print(webhook.secret) # store it to verify signatures ``` For a single job, pass `callback_url` with the upload instead. Scripts and notebooks can wait in place with `rv.batch.wait(jobId)` (Node.js) or `rv.batch.wait(job_id)` (Python), which polls every 5 seconds; raise its timeout for large lists. [Webhooks](https://docs.rocketverifier.com/api/webhooks) covers payloads and signature checks. ## Download the segments Download the results as CSV or JSON, all at once or one segment at a time with `filter`: | `filter` | Rows | | --- | --- | | `send_safe` | Every deliverable address plus catch-all addresses scoring 65 or more, without disposable or role addresses | | `deliverable` | Mailbox confirmed | | `risky` | Accepts mail with a named risk; includes catch-all under result version `2026-11-01` | | `undeliverable` | Will bounce | | `unknown` | No conclusive answer, refunded | cURL: ```bash curl "https://api.rocketverifier.com/v1/jobs/$JOB_ID/download?filter=send_safe&include_original=true" \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "RocketVerifier-Version: 2026-11-01" \ -o send-safe.csv ``` Node.js: ```js import { writeFile } from "node:fs/promises"; const csv = await rv.batch.download(upload.jobId, { filter: "send_safe", includeOriginal: true }); await writeFile("send-safe.csv", csv); ``` Python: ```python csv = rv.batch.download(upload.job_id, filter="send_safe", include_original=True) with open("send-safe.csv", "w") as f: f.write(csv) ``` `include_original=true` puts your uploaded columns first, so the file drops straight back into your email platform. Each row also carries `sub_status`, `did_you_mean`, `catch_all_verdict`, `catch_all_score` and the other detail columns. ## Decide what to keep Keep what will deliver, remove what will bounce or harm your reputation, and hold the rest for another look. | Segment | Action | | --- | --- | | `deliverable` | Keep | | `risky` + `catch_all`, verdict `send_safe` | Keep | | `risky` + `catch_all`, verdict `send_with_caution` | Send to engaged contacts first, watch bounces | | `risky` + `role_based` | Keep for B2B and transactional mail | | `risky` + `mailbox_full` | Suppress for now, re-verify in a later run | | `risky` + `possible_trap`, `toxic`, `do_not_mail`, `accepts_then_bounces`, `parked_domain` | Remove | | `risky` + `catch_all`, verdict `avoid` | Remove | | `undeliverable` (including `disposable`) | Remove. Fix `did_you_mean` typos only when the contact confirms them. | | `unknown` | Hold, and re-verify in a new job after a few hours | Mail the kept addresses through a connected SendGrid, Mailgun or Postmark account and the [Bounce Guarantee](https://docs.rocketverifier.com/integrations/bounce-guarantee) refunds every hard bounce on a deliverable result automatically. ## Keep the list fresh Mailboxes close and domains lapse, so a clean list does not stay clean. Build verification into the list's lifecycle: - **Before each campaign,** re-verify every address whose last check is older than 30 days. The native connectors use the same 30 day window by default and skip contacts verified more recently. - **Unknown results** go into a new job after their `retry_after`. They cost nothing until they return a real answer. - **New contacts** are best verified at the point of capture. See [verify at signup](https://docs.rocketverifier.com/guides/signup-verification). - **Lists in a CRM or email platform** stay clean on a schedule with a [native connector](https://docs.rocketverifier.com/guides/crm-hygiene), which writes the results back to each contact. ### Watch a list with a monitor A list health monitor re-verifies a saved list of up to 5,000 addresses daily or weekly and alerts you when the share of invalid and risky addresses passes your threshold. Each run is charged like a bulk job, 1 credit per unique address with unknown results refunded. A domain authentication monitor watches your sending domain's SPF, DKIM, DMARC and blocklist status for free. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/monitors \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "VIP customers", "type": "list_health", "frequency": "weekly", "alert_threshold": 5, "emails": ["maya@northwind.io", "li.wei@lakeside-dental.com"] }' ``` Alerts arrive as a `monitor.alert` webhook. The [monitors reference](https://docs.rocketverifier.com/api/monitors) covers every field. ## Next steps - [Bulk upload reference](https://docs.rocketverifier.com/api/bulk-upload) Every upload, preview and confirm field. - [Reading results](https://docs.rocketverifier.com/results) What every status and sub_status means and costs. - [Keep a CRM clean](https://docs.rocketverifier.com/guides/crm-hygiene) Scheduled syncs that write results back to each contact. - [Webhooks](https://docs.rocketverifier.com/api/webhooks) Signed events for finished jobs and monitor alerts. ## Frequently asked questions ### How big can a list be? A file upload takes up to 500,000 unique addresses and 50 MB, as CSV, TSV, TXT or XLSX. The JSON bulk endpoint takes up to 100,000 addresses per request. ### Am I charged for duplicates? No. Addresses are deduplicated case-insensitively before charging, and each unique address costs 1 credit. Unknown results are refunded when the job completes. ### Is the preview really free? Yes. The preview runs syntax, disposable, role, MX, duplicate and suppression checks on every row, plus a live mailbox check on a random sample, and charges nothing. You decide whether to verify after reading it. ### How long does a job take? Bulk verification runs at up to 100,000 emails per hour. Register a job.completed webhook instead of waiting on the request. ### Can I get the results in the same columns as my old verifier? Yes. Add columns=zerobounce, bouncer or kickbox to the download to get a CSV in that tool's column layout, with the closest equivalent values, so existing imports keep working. --- # Keep your CRM clean Source: https://docs.rocketverifier.com/guides/crm-hygiene > Connect your CRM or email platform once, pick a source and a schedule, and RocketVerifier verifies the contacts and writes status, sub status, score, verified date and a Send, Review or Remove recommendation back to each one. Recently verified contacts are skipped for free, action rules tag, unsubscribe or move bad contacts, and destructive actions never touch catch-all or unknown results. A CRM decays on its own: people change jobs, domains lapse and typos from old imports sit there until the next campaign bounces. A native connector verifies the contacts where they live and keeps them verified on a schedule, with no exports or imports. ## How a sync works Each sync reads contacts from one source, verifies the ones that need it, and writes the results back. **Step 1. Read the source** The connector reads the source you picked: all contacts, or one list, audience, segment, view or campaign, depending on the platform. **Step 2. Skip what is fresh** Contacts verified within the skip window are left out and cost nothing. Contacts you verified recently anywhere else in RocketVerifier are written back from that result, also for free. **Step 3. Verify the rest** The remaining contacts run as one bulk job, 1 credit per unique address. Unknown results are refunded when the job completes. **Step 4. Write back and act** Results are written to fields or tags on each contact, then your action rules run. The run's report lands in the sync history, and an `integration.sync.completed` [webhook](https://docs.rocketverifier.com/api/webhooks) fires. ## Connect a platform Open **Integrations** in the [dashboard](https://app.rocketverifier.com/dashboard/integrations) and pick the platform. OAuth platforms send you to the platform to approve access; API key platforms validate the credentials against the platform before anything is saved. Then pick the source, the schedule and the write-back options, and click **Sync now** or wait for the schedule. Each platform has its own page with the exact source types, field names and actions it supports: - [HubSpot](https://docs.rocketverifier.com/integrations/hubspot) Contact properties, lists, new-contact auto-verify. - [Salesforce](https://docs.rocketverifier.com/integrations/salesforce) Leads and Contacts, list views and campaigns. - [Mailchimp](https://docs.rocketverifier.com/integrations/mailchimp) Audiences, status tags and unsubscribes. - [Pipedrive](https://docs.rocketverifier.com/integrations/pipedrive) People, filters and custom fields. - [Klaviyo](https://docs.rocketverifier.com/integrations/klaviyo) Lists, profile properties and suppression. - [All integrations](https://docs.rocketverifier.com/integrations) CRMs, email, cold outreach, ecommerce and forms. ## Choose a schedule and sync mode The schedule decides how often the source is re-read; the sync mode and skip window decide which contacts are verified. | Setting | Options | Recommendation | | --- | --- | --- | | Schedule | Manual only, Daily, Weekly, Monthly | Weekly for active CRMs, Monthly for large, slow-moving lists | | Scheduled sync mode | Full (every contact, minus recently verified) or Incremental (changed since the last sync) | Incremental for daily and weekly schedules, Full for monthly | | Skip contacts verified in the last | 0 to 365 days, default 30 | Keep 30. `0` re-verifies everything and uses more credits. | Incremental syncs read only contacts created or changed since the last sync; the first incremental run reads everything. Under **Re-checks and freshness** you can also give each result type its own interval, for example re-checking valid contacts every 90 days and unknown ones every 7. ### Quarantine uncertain contacts Turn on **Quarantine and re-check uncertain contacts** to re-verify risky, catch-all and unknown contacts automatically every few days (1 to 90, default 14). They carry the Review recommendation meanwhile, and each re-check moves them to Send or Remove once the answer is clear. ### Alerts **Alert me about spikes of bad emails** sends an email when a sync, or the platform's new sign-ups, suddenly contain far more invalid addresses than usual. It is on by default. ## Write results back Results land on each contact, where your team and your platform's own automations can use them. **Status fields** hold the status, sub status, score, verified date and a recommendation. Field names depend on the platform: HubSpot properties such as `rv_email_status` are created automatically, and Salesforce uses `RV_Email_Status__c` style custom fields. You can map any of them to fields you already have. | Recommendation | Results | | --- | --- | | Send | Valid | | Review | Risky, catch-all, unknown | | Remove | Invalid, disposable | **Status tags** add a tag per result, with a prefix you choose, such as `rv-status:invalid`, on platforms that use tags. Build segments and workflows on the recommendation field: one field, three values, the same on every platform. ## Set action rules Action rules go beyond labels: for each result type (valid, invalid, disposable, risky, catch-all, unknown), choose what happens to the contact on the platform. | Action | Effect | | --- | --- | | Do nothing | Write fields and tags only | | Add tag | Adds the tag you name | | Move to list | Adds the contact to the list you pick | | Pause in campaigns | Stops the lead in cold outreach sequences | | Unsubscribe | Unsubscribes or opts out the contact | | Suppress (blocklist) | Adds the contact to the platform's blocklist or suppression list | | Delete permanently | Removes the contact from the platform | The actions offered depend on what each platform supports. Three safeguards apply to every rule: - **Destructive actions are only for certain results.** Unsubscribe, suppress and delete never apply to catch-all or unknown results, which are often real people or a timeout. - **Preview before acting.** With this on, results are written as usual but actions wait until you approve the run in the sync history. You get an email with the planned changes. - **Undo and backups.** Every run records each change it made. **Undo this run** reverses the actions the platform can reverse, and a CSV backup of each run's changes is kept for 90 days. Start with **Add tag** for invalid and disposable contacts, check the tagged contacts once, then switch to unsubscribe or delete when you trust the rules. ## Verify new contacts as they arrive On platforms that send new-contact events, such as HubSpot, Shopify, BigCommerce, Typeform, Jotform and Webflow, turn on **Auto-verify new contacts**. Each new contact is verified within moments of being created (1 credit each) and written back. - **Also verify existing contacts once** runs one full sync when you turn auto-verify on. Contacts verified recently are skipped. - **Send an email.verified webhook for each new contact** forwards each result to your own [webhook](https://docs.rocketverifier.com/api/webhooks), with `source` set to the platform. ## Protect cold outreach campaigns On Instantly, Smartlead, lemlist, Apollo, Reply.io, Woodpecker and Outreach, the **Campaign safety net** checks campaigns every hour. It verifies leads newly added to campaigns, and every lead of campaigns not launched yet, and pauses or block-lists invalid and disposable leads before they are emailed. Each new lead costs 1 credit; leads already checked are free. ## Feed bounces back Connect the platform you send through, SendGrid, Mailgun, Amazon SES or Postmark, and its hard bounces and complaints go straight onto your suppression list. With **Import bounces daily**, RocketVerifier also reads the platform's bounce feed once a day, in addition to real-time webhooks. With SendGrid, Mailgun and Postmark, every confirmed hard bounce of a deliverable result is refunded under the [Bounce Guarantee](https://docs.rocketverifier.com/integrations/bounce-guarantee). ## Reuse settings across platforms **Cleaning policies**, on the Integrations page, save a schedule, sync mode, skip window, quarantine, alerts and action rules under one name. Apply a policy to several integrations at once, so every platform follows the same rules. ## Next steps - [Integrations](https://docs.rocketverifier.com/integrations) Every native connector, with fields, sources and actions. - [Clean a list](https://docs.rocketverifier.com/guides/list-cleaning) Verify a one-off file with a free preview. - [Reading results](https://docs.rocketverifier.com/results) What every status and sub_status means. - [Bounce Guarantee](https://docs.rocketverifier.com/integrations/bounce-guarantee) Automatic refunds for hard bounces on deliverable results. ## Frequently asked questions ### Am I charged again for contacts that were verified recently? No. Contacts verified within the skip window (30 days by default) are skipped, and contacts you verified recently in any other job are written back from that result for free. Unknown results are refunded. ### Can a sync delete or unsubscribe a real person by mistake? Destructive actions (unsubscribe, suppress, delete) only apply to results we are sure about, never to catch-all or unknown results, whatever rule you set. Turn on Preview before acting to approve each run's changes first. ### Can I undo a sync? Yes, for actions the platform can reverse. Every run records its changes, Undo this run reverses them, and a CSV backup of each run's changes is kept for 90 days, deleted contacts included. ### Which platforms are supported? More than 30, across CRMs, email marketing, cold outreach, sending platforms, ecommerce and forms, including HubSpot, Salesforce, Pipedrive, Mailchimp, Klaviyo, Brevo, Instantly, Smartlead, Shopify and Airtable. The integrations directory lists them all. --- # Errors Source: https://docs.rocketverifier.com/errors > Every error returns the same JSON shape, an error object with a stable code, a readable message and optional details. Branch on error.code, not the message. Retry 429, 5xx and network failures with the same Idempotency-Key; fix the request for every other 4xx. When a request fails, the HTTP status says what kind of problem it is and `error.code` says exactly which one. Codes are stable, so your code can branch on them; messages are written for people and can change. ## Error shape Every error response, from every endpoint, has this body: Error body: ```json { "error": { "code": "insufficient_credits", "message": "Need 2500 credits, have 1200", "details": { "required": 2500, "available": 1200 } } } ``` | Field | Type | Meaning | | --- | --- | --- | | `error.code` | string | Machine-readable code. Branch on this. | | `error.message` | string | What went wrong, in plain words. Safe to log; show it to developers, not end users. | | `error.details` | object or null | Extra data for some codes, such as `required` and `available` credits or the `errors` list of a validation failure. | Every response also carries an `X-Request-ID` header. Send your own `X-Request-ID` (up to 128 characters) to tie API calls to your logs, and include it when you contact support. ## Authentication and access errors | Status | `error.code` | Cause | Fix | | --- | --- | --- | --- | | 401 | `unauthorized` | Missing `Authorization` header, missing `Bearer ` prefix, or an unknown or revoked key | Send `Authorization: Bearer ` with an active key | | 401 | `api_key_expired` | The key passed its expiry date | Extend the expiry or create a new key | | 401 | `invalid_token` | OAuth access token expired, revoked, or its app suspended | Refresh the token, or reconnect the user | | 403 | `insufficient_scope` | The key or token lacks the scope this endpoint needs | Add the scope to the key or request it in your app | | 403 | `ip_not_allowed` | The caller's IP is outside the key's or organization's allowlist | Add the IP or range to the allowlist | | 403 | `sandbox_key_restricted` | An `rv_test_` key was used on a real address, or for a file upload | Use a live key, or sandbox addresses | | 403 | `account_suspended` | The account is suspended | Contact support@rocketverifier.com | | 403 | `forbidden` | The request is not allowed for this account | Check the account and resource | [Authentication](https://docs.rocketverifier.com/authentication) explains keys, scopes, expiry and allowlists. ## Credit errors | Status | `error.code` | Cause | Fix | | --- | --- | --- | --- | | 403 | `insufficient_credits` | The balance is zero, so the request was refused before any work. Applies to verification, jobs, monitors, finder and uploads. | Add credits or turn on auto-recharge | | 402 | `insufficient_credits` | The balance ran out while charging, or a bulk job needs more credits than remain. `details` holds `required` and `available`. | Add credits, or split the job | | 402 | `api_key_spend_cap_reached` | The key's or app connection's monthly credit limit is used up. `details` holds `monthly_limit`, `used_this_month` and `required`. | Raise the limit, or wait for the next month (UTC) | Read-only endpoints such as `GET /v1/credits`, `GET /v1/me` and the webhook endpoints work at a zero balance. ## Request errors | Status | `error.code` | Cause | Fix | | --- | --- | --- | --- | | 422 | `validation_error` | The body is not valid JSON, a required field is missing, or a value is out of range (for example `timeout` outside 3 to 60). `details.errors` lists each problem. | Fix the fields listed in `details.errors` | | 400 | `bad_request` | The request is malformed | Check the method, path and body | | 400 | `no_emails` | A bulk request or file has no addresses | Send at least one address | | 400 | `too_many_emails` | More than 100,000 unique addresses in a bulk request, or more than 5,000 in a monitor | Split the list into several jobs | | 400 | `invalid_email` | The address is not a valid email | Fix the address | | 400 | `invalid_domain` | The domain parameter is not a domain name | Send a bare domain such as `northwind.io` | | 400 | `invalid_ip` | The IP parameter is not a public IPv4 address | Send an address such as `192.0.2.10` | | 400 | `invalid_name` | `first_name` for the finder has no letters | Send a real first name | | 400 | `invalid_url` | A webhook URL is not HTTPS | Use an `https://` URL | | 400 | `invalid_events` | A webhook subscribes to an unknown event | Use names from `GET /v1/webhooks/events` | | 400 | `no_changes` | An update request changes nothing | Send at least one field | | 400 | `domain_required`, `emails_required`, `invalid_emails`, `invalid_frequency` | A monitor is missing its domain or emails, has addresses that fail syntax checks, or an unknown frequency | Fix the monitor fields | | 400 | `job_not_complete` | A download was requested before the job finished | Wait for `job.completed`, then download | | 400 | `job_not_cancellable` | The job is no longer pending or processing | Nothing to do: it already finished | | 404 | `not_found` | The job, webhook, monitor or route does not exist for this account | Check the ID and the account behind the key | ## Upload errors These come from [`POST /v1/verify/bulk/upload`](https://docs.rocketverifier.com/api/bulk-upload) and its preview and confirm steps. | Status | `error.code` | Cause | Fix | | --- | --- | --- | --- | | 400 | `missing_file` | Neither or both of `file` and `source_url` were sent | Send exactly one | | 400 | `invalid_json` | A JSON body could not be parsed | Send a JSON object | | 400 | `invalid_column_mapping` | `column_mapping` or `email_column` is not valid | Use `{"email": "Work Email"}` or a 0-based index | | 400 | `unsupported_file_type` | The file is not `.csv`, `.tsv`, `.txt` or `.xlsx` | Convert the file | | 400 | `empty_file` | The uploaded file is empty | Upload the file again | | 400 | `invalid_callback_url`, `invalid_source_url` | The URL is not a public HTTPS URL | Use a public `https://` URL | | 411 | `length_required` | The upload has no `Content-Length` header | Let your HTTP client set it | | 413 | `file_too_large` | The file is over 50 MB | Split the file, or compress columns you do not need | | 415 | `unsupported_media_type` | The body is neither `multipart/form-data` nor JSON | Send a file as multipart, or `source_url` as JSON | | 409 | `preview_unavailable` | The job was not created with `preview=true` | Upload with `preview=true` to get a free preview | | 409 | `job_not_awaiting_confirmation` | The job was already confirmed, cancelled or finished | Read the job status instead | Problems found while reading the file fail the job and fire the `job.failed` webhook: no email column (`email_column_not_found`), no rows (`no_emails`), an unreadable spreadsheet (`invalid_file`) or more than 500,000 unique addresses (`too_many_emails`). ## Rate limit errors | Status | `error.code` | Cause | Fix | | --- | --- | --- | --- | | 429 | `rate_limited` | More requests in the last 60 seconds than the limit allows | Wait `Retry-After` seconds, then retry | | 429 | `daily_limit_reached` | The free test lookup (`POST /v1/tools/verify-free`) allows 2 checks per IP per day | Use `POST /v1/verify` with an API key | A `rate_limited` response carries `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers, and `details.retry_after_seconds`. [Rate limits](https://docs.rocketverifier.com/rate-limits) lists the limits for each plan. ## Server errors | Status | `error.code` | Cause | Fix | | --- | --- | --- | --- | | 500 | `internal_error`, `verification_failed`, `finder_failed`, `create_failed` | The request could not be completed | Retry with backoff and the same `Idempotency-Key` | | 502 | `storage_unavailable` | An uploaded file could not be stored | Retry the upload | | 503 | `service_unavailable`, `queue_unavailable` | A dependency is briefly unavailable | Retry with backoff | | 503 | `maintenance` | Bulk intake is paused for maintenance. Carries `Retry-After: 600`. | Retry after the given seconds | | 503 | `idempotency_unavailable` | An `Idempotency-Key` was sent but the idempotency store is unreachable, so the request was refused rather than risk a double charge | Retry shortly with the same key | ## RocketShield widget errors The [RocketShield](https://docs.rocketverifier.com/integrations/widget) form widget calls its own endpoint with a public key and returns a flat body, `{"code": "...", "message": "..."}`. | Status | `code` | Cause | Fix | | --- | --- | --- | --- | | 401 | `missing_key`, `invalid_key` | The embed has no key, or the key is unknown or inactive | Copy the embed code again from the dashboard | | 403 | `origin_required`, `domain_not_allowed` | The page's domain is not on the key's allowed domains | Add the domain to the shield's settings | | 402 | `insufficient_credits` | The account has no credits | Add credits | ## Which errors to retry Retry only when the same request can succeed later. Everything else needs a change first. | Retry | Do not retry without a change | | --- | --- | | `429` after `Retry-After` seconds | `400`, `404`, `409`, `411`, `413`, `415`, `422`: fix the request | | `500`, `502`, `503` with exponential backoff | `401`: fix or refresh the credential | | Network errors and timeouts | `402`, `403`: add credits, scopes or allowlist entries | Send an `Idempotency-Key` on every `POST`, and reuse it on each retry of the same logical request. Within 24 hours the API returns the stored result instead of verifying and charging again. An `unknown` verification result is a `200`, not an error: retry it after its `retry_after` seconds, as described in [reading results](https://docs.rocketverifier.com/results#retry-unknown-results). ## Handle errors in code This client retries what is safe to retry, honours `Retry-After`, reuses one idempotency key across attempts and surfaces everything else with its code. Node.js: ```js import { randomUUID } from "node:crypto"; const RETRYABLE = new Set([429, 500, 502, 503]); export class RocketVerifierApiError extends Error { constructor(status, body, requestId) { super(body?.error?.message ?? `HTTP ${status}`); this.status = status; this.code = body?.error?.code ?? "unknown_error"; this.details = body?.error?.details ?? null; this.requestId = requestId; } } export async function rvRequest(path, body, { maxAttempts = 4 } = {}) { const idempotencyKey = randomUUID(); // same key for every attempt for (let attempt = 1; ; attempt++) { let res; try { res = await fetch(`https://api.rocketverifier.com${path}`, { method: "POST", headers: { Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify(body), signal: AbortSignal.timeout(35_000), }); } catch (networkError) { if (attempt >= maxAttempts) throw networkError; await sleep(backoff(attempt)); continue; } if (res.ok) return res.json(); const errorBody = await res.json().catch(() => null); if (RETRYABLE.has(res.status) && attempt < maxAttempts) { const retryAfter = Number(res.headers.get("Retry-After")); await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt)); continue; } throw new RocketVerifierApiError(res.status, errorBody, res.headers.get("X-Request-ID")); } } const backoff = (attempt) => Math.min(30_000, 500 * 2 ** attempt) + Math.random() * 250; const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); try { const result = await rvRequest("/v1/verify", { email: "maya@northwind.io" }); console.log(result.status); } catch (err) { if (err.code === "insufficient_credits") notifyBilling(err.details); else if (err.code === "api_key_spend_cap_reached") alertOps(err.details); else throw err; } ``` Python: ```python import os import random import time import uuid import requests RETRYABLE = {429, 500, 502, 503} class RocketVerifierApiError(Exception): def __init__(self, status: int, body: dict | None, request_id: str | None): error = (body or {}).get("error") or {} super().__init__(error.get("message") or f"HTTP {status}") self.status = status self.code = error.get("code", "unknown_error") self.details = error.get("details") self.request_id = request_id def backoff(attempt: int) -> float: return min(30.0, 0.5 * 2**attempt) + random.random() / 4 def rv_request(path: str, body: dict, max_attempts: int = 4) -> dict: idempotency_key = str(uuid.uuid4()) # same key for every attempt for attempt in range(1, max_attempts + 1): try: res = requests.post( f"https://api.rocketverifier.com{path}", headers={ "Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=body, timeout=35, ) except requests.RequestException: if attempt == max_attempts: raise time.sleep(backoff(attempt)) continue if res.ok: return res.json() if res.status_code in RETRYABLE and attempt < max_attempts: retry_after = int(res.headers.get("Retry-After") or 0) time.sleep(retry_after or backoff(attempt)) continue try: error_body = res.json() except ValueError: error_body = None raise RocketVerifierApiError(res.status_code, error_body, res.headers.get("X-Request-ID")) try: result = rv_request("/v1/verify", {"email": "maya@northwind.io"}) print(result["status"]) except RocketVerifierApiError as err: if err.code == "insufficient_credits": notify_billing(err.details) elif err.code == "api_key_spend_cap_reached": alert_ops(err.details) else: raise ``` ### With the SDKs The Node.js and Python SDKs already retry `429` responses (honouring `Retry-After`) and network errors, up to 3 times by default with the same idempotency key. They raise typed errors that carry `code`, the HTTP status and `details`: | Situation | Node.js | Python | | --- | --- | --- | | Invalid, missing or expired key | `AuthenticationError` | `AuthenticationError` | | Expired or revoked OAuth token | `InvalidTokenError` | `InvalidTokenError` | | Out of credits | `InsufficientCreditsError` (402) | `InsufficientCreditsError` (402 and 403) | | Still rate limited after retries | `RateLimitError` | `RateLimitError` | | Invalid request | `ValidationError` (400) | `ValidationError` (400 and 422) | | Scope, allowlist or sandbox refusal | `RocketVerifierError` with `code` | `PermissionDeniedError` with `code` | | Anything else | `RocketVerifierError` | `RocketVerifierError` | Check `err.code` in either SDK for the exact API code, such as `ip_not_allowed` or `api_key_spend_cap_reached`. The SDK pages, [Node.js](https://docs.rocketverifier.com/sdks/nodejs) and [Python](https://docs.rocketverifier.com/sdks/python), list every class. ## Next steps - [Rate limits](https://docs.rocketverifier.com/rate-limits) Limits per plan, headers and backoff for 429. - [Authentication](https://docs.rocketverifier.com/authentication) Keys, scopes, expiry, IP allowlists and spend caps. ## Frequently asked questions ### Is it safe to retry a POST that timed out? Yes, when you send an Idempotency-Key header. A retry with the same key within 24 hours returns the original result and never charges twice. The Node.js and Python SDKs add a key to every POST automatically. ### Why do I get 403 insufficient_credits and sometimes 402 insufficient_credits? 403 means the balance was already zero, so the request was refused before any work. 402 means the balance ran out while charging this request, for example a bulk job larger than the remaining credits. Both are fixed by adding credits. ### Are failed requests charged? No. Credits are only spent on a successful verification that returns a result. Errors, unknown results and requests refused for credits, scope or rate limits cost nothing. ### What should I send to support about an error? The X-Request-ID response header, the error code and the time of the request. Every response carries an X-Request-ID, and you can set your own on the request to match your logs. --- # Rate limits Source: https://docs.rocketverifier.com/rate-limits > Each account gets a fixed number of requests per rolling 60 second window, 30 on the free plan, 300 once you have bought credits, 600 with a monthly or yearly subscription, and 5 per IP without a key. Every response carries X-RateLimit headers, and a 429 tells you exactly how many seconds to wait. Verify lists with bulk jobs, which count as one request for up to 100,000 addresses. Rate limits keep the API fast for everyone. They count requests, not addresses, so the right endpoint choice matters more than the number itself. ## Limits by plan Limits apply per rolling 60 second window. The plan is detected automatically from your account. | Plan | Requests per minute | Who is on it | | --- | --- | --- | | Free | 30 | Accounts that have not bought credits yet | | Trial | 30 | Accounts on a trial | | Pay as you go | 300 | Accounts that have bought credits at least once | | Pro | 600 | Accounts with an active monthly or yearly subscription | | Anonymous | 5 per IP address | Requests without an API key, such as sandbox calls | The window slides: each request counts for exactly 60 seconds after it was made, so there is no burst at the top of the minute. ## How requests are counted Every authenticated request counts against one bucket, chosen by the credential: | Credential | Bucket | Limit | | --- | --- | --- | | Personal API key (`rv_live_`, `rv_test_`) | Your account | Your plan, or the key's override | | OAuth token for a personal account | That account | The account's plan | | Organization API key | The organization | The organization's limit, or the owner's plan when none is set | | OAuth token for an organization | The organization | The organization's limit | | No key | The caller's IP address | 5 per minute | All the personal keys on one account share its bucket, so splitting traffic across keys does not raise the limit. Keys with their own limit (see below) count in a separate bucket at that limit. Organization traffic has its own bucket, separate from every member's personal keys. ## Rate limit headers Every response carries the state of your bucket: | Header | Meaning | | --- | --- | | `X-RateLimit-Limit` | Requests allowed per 60 seconds for this bucket | | `X-RateLimit-Remaining` | Requests left in the current window | | `X-RateLimit-Reset` | Unix time (seconds) when the oldest request in the window expires | | `Retry-After` | On `429` only: seconds to wait before the next request | Response headers: ```http HTTP/2 200 X-RateLimit-Limit: 300 X-RateLimit-Remaining: 287 X-RateLimit-Reset: 1762854157 ``` ## Check your current limit `GET /rate-limit` returns the limit that applies to your key, where it comes from and how much of it is used. It counts as one request. cURL: ```bash curl https://api.rocketverifier.com/rate-limit \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Response 200: ```json { "success": true, "tier": "payg", "subscription_type": "free", "limit_source": "plan", "limit": 300, "remaining": 287, "used": 13, "reset_at": 1762854157 } ``` `limit_source` is `plan` when the plan tier applies and `api_key` when the key has its own limit. ## Per-key and organization limits A key can carry its own requests-per-minute limit that replaces the plan tier, higher or lower. Organizations can carry one limit for all their keys, and a single organization key can override it. These limits are set by our team: email support@rocketverifier.com with the key or organization and the volume you need. Lower limits are useful too: cap a batch import key at a low rate so it never crowds out your signup traffic. ## Endpoint limits A few endpoints have an extra limit on top of your plan: | Endpoint | Extra limit | | --- | --- | | `POST /v1/finder` | 20 requests and 40 mailbox checks per minute per account | | `POST /v1/tools/verify-free` | 2 lookups per IP per day (`429 daily_limit_reached`) | ## Handle 429 responses A `429` means the bucket is full. Wait the number of seconds in `Retry-After`, then send the same request again. 429 rate_limited: ```json { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Please try again later.", "details": { "limit": 300, "reset_at": "2026-11-11T09:42:37+00:00", "retry_after_seconds": 12 } } } ``` The SDKs do this for you: they wait `Retry-After` and retry up to 3 times with the same idempotency key. With plain HTTP, wrap your calls: Node.js: ```js async function withRateLimit(send, maxAttempts = 5) { for (let attempt = 1; ; attempt++) { const res = await send(); if (res.status !== 429 || attempt === maxAttempts) return res; const wait = Number(res.headers.get("Retry-After")) || 2 ** attempt; await new Promise((r) => setTimeout(r, wait * 1000 + Math.random() * 250)); } } const idempotencyKey = crypto.randomUUID(); const res = await withRateLimit(() => fetch("https://api.rocketverifier.com/v1/verify", { method: "POST", headers: { Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ email: "maya@northwind.io" }), }) ); ``` Python: ```python import os import random import time import uuid import requests def with_rate_limit(send, max_attempts: int = 5) -> requests.Response: for attempt in range(1, max_attempts + 1): res = send() if res.status_code != 429 or attempt == max_attempts: return res wait = int(res.headers.get("Retry-After") or 2**attempt) time.sleep(wait + random.random() / 4) return res idempotency_key = str(uuid.uuid4()) res = with_rate_limit( lambda: requests.post( "https://api.rocketverifier.com/v1/verify", headers={ "Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}", "Idempotency-Key": idempotency_key, }, json={"email": "maya@northwind.io"}, timeout=35, ) ) ``` To avoid `429`s in the first place, pace requests from `X-RateLimit-Remaining`: when it drops near zero, pause until `X-RateLimit-Reset`. ## Bulk or single requests Pick the endpoint by how the addresses arrive, not by how many you have. | Situation | Use | Requests used | | --- | --- | --- | | One address at a time, a person is waiting (signup, checkout) | [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify) | 1 per address | | A list you already have, up to 100,000 addresses | [`POST /v1/verify/bulk`](https://docs.rocketverifier.com/api/batch) | 1 per job | | A CSV, TSV, TXT or XLSX file, up to 500,000 addresses | [`POST /v1/verify/bulk/upload`](https://docs.rocketverifier.com/api/bulk-upload) | 1 per job | | Waiting for a job to finish | A [`job.completed` webhook](https://docs.rocketverifier.com/api/webhooks) | 0 | Looping over `POST /v1/verify` for a list of 10,000 addresses takes over half an hour at 300 requests per minute. One bulk job takes one request and runs at up to 100,000 emails per hour. If you poll job progress instead of using a webhook, poll every 5 seconds or slower. ## Next steps - [Errors](https://docs.rocketverifier.com/errors) Every error code and which ones to retry. - [Bulk verification](https://docs.rocketverifier.com/api/batch) Verify up to 100,000 addresses in one request. ## Frequently asked questions ### Do all my API keys share one limit? Yes. Personal keys and OAuth connections to your personal account share your account's limit. Organization keys share one separate limit for the whole organization. ### Does a bulk job count as one request? Yes. POST /v1/verify/bulk counts as one request for up to 100,000 addresses, and a file upload counts as one request for up to 500,000. Use them instead of looping over POST /v1/verify. ### How do I get a higher limit? Buying credits once moves an account from 30 to 300 requests per minute, and a monthly or yearly subscription raises it to 600. For more, email support@rocketverifier.com with your expected volume and we set a limit on your key or organization. ### Do sandbox requests count? Yes. Requests with an rv_test_ key count against your account's limit, and sandbox requests without a key count against the anonymous limit of 5 per minute per IP. --- # Teams and organizations Source: https://docs.rocketverifier.com/teams > An organization groups teammates under one account with five roles (owner, admin, member, billing and viewer). With credit pooling on, members' verifications are paid from a shared balance, and organization API keys act for the team with their own rate limit and IP allowlist. Create the organization and invite people from the Team page in the dashboard. An organization lets a team share one RocketVerifier setup: members with clear permissions, one credit pool, shared API keys and single sign-on. ## Create an organization Open **Team** in the [dashboard](https://app.rocketverifier.com/dashboard/team) and create an organization with its name. You become its owner. Then invite your teammates from the **Members** tab. **Step 1. Invite members** Enter a teammate's email and pick a role. They get an invitation link that is valid for 7 days. Owners and admins can see pending invitations and cancel them. **Step 2. Set up shared credits** Ask our team to turn on credit pooling and fund the pool, so members' verifications draw from one balance. See [pooled credits](#pooled-credits). **Step 3. Secure sign-in** Owners and admins can connect a SAML identity provider in the **SSO** tab and require SSO for every member. See [single sign-on](#single-sign-on). ## Roles Each member has exactly one role. Invitations can grant any role except owner; ownership is transferred, never shared. | Role | Can do | | --- | --- | | `owner` | Everything: organization settings, deleting the organization, members, billing, API keys, audit log | | `admin` | Manage and remove members, manage API keys, change settings, view the audit log | | `member` | Verify, view API keys and create their own | | `billing` | View and manage billing | | `viewer` | View API keys and the audit log | To transfer ownership, the owner changes another member's role to owner. The previous owner becomes an admin. The owner cannot leave or be removed until ownership has moved. ## Pooled credits With credit pooling on, every charge for a member's verification is taken from the organization's shared pool when the pool covers the full amount. That includes requests made with the member's personal API keys. - **Pool first.** A charge goes to the pool whenever it holds at least the full amount. A bulk job is charged in one go. - **Never split.** If the pool cannot cover the whole charge, the member's personal balance pays instead. - **Refunds follow the charge.** Unknown results, failed jobs and cancelled jobs refund the balance that paid. - **Traceable.** Charges paid by the pool appear in the credit history with an `[Org pool]` prefix, and the **Credits** tab shows usage by member. Credits bought on the Buy credits page go to your personal balance. Credit pooling and pool top-ups are arranged with our team: email support@rocketverifier.com. ### Balance checks on personal keys A personal API key checks the member's own balance before work starts: `POST /v1/verify` needs at least 1 personal credit, and a bulk job needs as many personal credits as it has unique addresses, even when the pool will pay. Organization API keys check the larger of the pool and the owner's balance, so they are the right choice for shared services that should run on the pool. ## Organization API keys An organization API key belongs to the team rather than a person. It: - Acts as, and is billed to, the organization's owner, so charges draw from the pool first when pooling is on. - Uses one rate limit bucket for the whole organization, separate from members' personal keys. The organization's limit applies, or the owner's plan limit when none is set. - Accepts requests only from the organization's IP allowlist when one is set, and returns `403 ip_not_allowed` otherwise. - Uses result version `2025-01-01` unless the request sends `RocketVerifier-Version: 2026-11-01`. See [result versions](https://docs.rocketverifier.com/versioning). Organization keys and organization IP allowlists are issued by our team. Email support@rocketverifier.com with the organization and the scopes the key needs. ## Single sign-on Organizations can sign members in through a SAML identity provider. In the **SSO** tab, owners and admins: 1. Verify the email domain with a DNS TXT record. 2. Enter the identity provider's metadata URL, or its SSO URL, entity ID and signing certificate. 3. Run a test sign-in, then enable SSO, and optionally require it for all members. The tab shows the ACS URL, entity ID and metadata URL to paste into your identity provider. ## Audit log Owners, admins and viewers can read the organization's audit log in the **Audit** tab. It records member changes (invitations, role changes, removals) and organization settings changes, with who made each change and when. ## Apps connected to an organization When a member who is an owner or admin connects a third-party app through [RocketVerifier Connect](https://docs.rocketverifier.com/oauth), they can connect it to the organization instead of their personal account. The app then acts as the organization: billed to the pool, limited by the organization's rate limit and IP allowlist. If that member later loses the owner or admin role, the connection stops working with `401 invalid_token`. ## Next steps - [Authentication](https://docs.rocketverifier.com/authentication) Keys, scopes, expiry, IP allowlists and monthly spend caps. - [Rate limits](https://docs.rocketverifier.com/rate-limits) How organization requests are counted. ## Frequently asked questions ### Are credits I buy added to the organization pool? No. Purchases on the Buy credits page go to your personal balance. The organization pool is set up and funded with our team; email support@rocketverifier.com. ### What happens when the pool cannot cover a charge? The whole charge goes to the member's personal balance instead. A charge is never split between the pool and a personal balance, and refunds go back to whichever balance paid. ### How long does an invitation last? Seven days. Owners and admins can cancel a pending invitation from the Members tab and send a new one. ### Can I delete my account while I own an organization? Only when you are its last member. If the organization has other members, transfer ownership or remove them first. --- # GDPR and data handling Source: https://docs.rocketverifier.com/gdpr > RocketVerifier processes the addresses you submit on your behalf, as a data processor, and never emails them. Bulk results are deleted automatically after 90 days by default, and you choose the window. Export your data or delete your account yourself from Settings, and request a Data Processing Agreement from legal@rocketverifier.com. When you verify an address, you decide which addresses are processed and why. RocketVerifier processes them on your behalf, as a data processor under the GDPR, only to return verification results. Lists are never sold or shared. ## What RocketVerifier stores Each kind of data has its own retention, and you control the one that holds your lists. | Data | What it holds | Kept for | | --- | --- | --- | | Account | Name, email, hashed password, settings | Until you delete the account | | Bulk job results | Each address with its status, sub status, score and detail, plus the original columns of uploaded files | Your retention window, 90 days by default | | Job records | Job name, counts and timestamps | Until you delete the account. Names and file names are removed when the job's results are purged. | | Credit history | Charges, refunds and purchases | Until you delete the account | | Billing records | Invoices and payment history | Retained as financial records after account deletion | | Suppression lists | Addresses you or your connected sending platforms marked do not mail | Until you remove them or delete the account | Single verifications with `POST /v1/verify` are returned to you and not stored as job rows. Payment card numbers are handled by the payment processor and never stored by RocketVerifier. ## Data retention A daily retention job deletes the result rows of finished jobs (completed, failed or cancelled) once they are older than your retention window. When every row of a job is gone, the job is renamed "Archived list (details purged)" and its file name is removed. Set the window under **Settings → Privacy** in the [dashboard](https://app.rocketverifier.com/dashboard/settings): 30, 60, 90, 180 or 365 days, or keep results until you delete them. The default is 90 days. ## Caches To answer quickly and avoid re-checking the same address, the verification service keeps short-lived caches. Address-level caches are keyed by a keyed hash of the address, never the address itself. | Cache | Contents | Expires after | | --- | --- | --- | | Verification result | The verdict for an address | 6 hours; 5 minutes for transient unknowns | | Verification history | Your own last 50 checks of an address (time, classification, score), for the activity scores | 90 days after the last check | | Idempotency | The stored response of a request sent with an `Idempotency-Key` | 24 hours | | Domain data | MX and DNS answers, SPF, DKIM and DMARC results, catch-all probes. No addresses. | 60 seconds to 7 days, by record | | Naming patterns | Per domain, counts of naming shapes such as `first.last`. No addresses. | 180 days | Retention settings and account deletion do not purge these caches; they expire on the schedule above. ## The data network By default, accounts share in the RocketVerifier data network: confirmed mailbox outcomes and bounce signals, stored as keyed hashes and domain-level counts, never readable addresses. It makes answers faster and sharpens [catch-all scoring](https://docs.rocketverifier.com/catch-all). Nothing from the network is returned to anyone as such: no other customer ever learns that you checked an address. Turn it off under **Settings → Privacy** by clearing **Share in the RocketVerifier data network**. Your account then neither contributes to the network nor reads from it, including the shared result cache. ## Export your data Download a copy of your account data from **Settings → Privacy → Export my data**. The JSON export includes your profile, recent credit history, recent jobs, your API keys (prefix and status only, never the key) and your invoices. This covers the right of access and the right to data portability. Download the full results of any job as CSV or JSON from the job page, or with [`GET /v1/jobs/{id}/download`](https://docs.rocketverifier.com/api/batch). ## Delete your account Delete your account from **Settings → Privacy → Delete account**. Deletion cancels any active subscription, signs out every session and removes your account and the data linked to it, including API keys, jobs and results. Your data is permanently removed within 30 days. Invoices, email logs and audit logs are retained as financial and security records. If you own an organization that still has other members, transfer ownership or remove them first. ## Requests from data subjects When a person asks you to erase or stop processing their address, you control everything RocketVerifier holds about it: 1. **Delete the jobs** that contain the address, or let your retention window remove them. 2. **Add the address to a suppression list** under **Suppression lists** in the dashboard. Later checks return `do_not_mail` without verifying it, and are free. 3. **Wait out the caches.** The cached verdict expires within 6 hours. For access requests about your own account, use the export above. For anything else, email privacy@rocketverifier.com. ## Security - **No email is ever sent** to the addresses you verify. - **TLS** encrypts every request to the API, the dashboard and the website. - **API keys** are shown once and stored as SHA-256 hashes. Passwords are stored as secure hashes. - **Account controls:** two-factor authentication, session management, SSO for organizations, and per-key IP allowlists, expiry dates and spend caps. See [authentication](https://docs.rocketverifier.com/authentication). - **Restricted production access,** with audit logging on that access. The [security page](https://www.rocketverifier.com/security/) and the [Trust Center](https://app.rocketverifier.com/trust) cover these practices in more detail. ## DPA and subprocessors - **Data Processing Agreement:** email legal@rocketverifier.com. - **Subprocessors:** the list is available on request from privacy@rocketverifier.com. They fall into four categories: payment processing, cloud infrastructure for hosting and verification jobs, cookieless usage analytics, and Cloudflare Turnstile bot protection on free tools. - **Privacy policy:** [rocketverifier.com/privacy-policy](https://www.rocketverifier.com/privacy-policy/). ## Next steps - [Teams](https://docs.rocketverifier.com/teams) Organizations, roles and pooled credits. - [Authentication](https://docs.rocketverifier.com/authentication) Lock keys down with allowlists, expiry dates and spend caps. ## Frequently asked questions ### Does RocketVerifier send emails to the addresses I verify? No. Verification uses DNS lookups and an SMTP conversation that ends before any message is sent. The people on your list never hear from RocketVerifier. ### How long are my uploaded lists kept? Result rows of finished jobs are deleted automatically after 90 days by default. Choose 30, 60, 90, 180 or 365 days, or keep them until you delete them, under Settings, Privacy. ### Is a Data Processing Agreement available? Yes. Email legal@rocketverifier.com for the DPA. The subprocessor list is available on request from privacy@rocketverifier.com. ### How do I handle a data subject's erasure request for an address I verified? Delete the jobs that contain it, or wait for your retention window, and add the address to a suppression list so it is not verified again. Cached results expire on their own within 6 hours. --- # API reference Source: https://docs.rocketverifier.com/api > The RocketVerifier API is a JSON REST API at https://api.rocketverifier.com/v1. Authenticate every call with an API key or OAuth access token in the Authorization Bearer header, branch on the error code when a call fails, and read the X-RateLimit headers to pace your traffic. Every RocketVerifier product, from the dashboard to the MCP server, runs on this API. It speaks JSON over HTTPS, uses one error shape everywhere and answers most single verifications in under half a second. ## Make your first request Send the key in the `Authorization` header and JSON in the body. This call checks your balance and costs nothing. cURL: ```bash curl https://api.rocketverifier.com/v1/credits \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); const balance = await rv.getCredits(); console.log(balance.credits); ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) print(rv.get_credits().credits) ``` All paths in this reference start with `/v1`. Request bodies are `application/json`, except file uploads, which use `multipart/form-data`. Timestamps are ISO 8601 in UTC. ## Authenticate requests Every endpoint that touches your account needs `Authorization: Bearer `. The credential is one of: | Credential | Prefix | Use it for | | --- | --- | --- | | Live API key | `rv_live_` | Server-side calls on your own account. | | Sandbox API key | `rv_test_` | Tests and CI. Accepts only `@sandbox.rocketverifier.com` addresses and never charges. | | Organization API key | `rv_live_` | Calls billed to an organization, with its shared rate limit and IP allowlist. | | OAuth access token | `rv_at_` | Apps acting for other RocketVerifier users through RocketVerifier Connect. | API keys carry scopes, and each endpoint checks one. A missing scope returns `403 insufficient_scope`. Keys can also have an expiry date, an IP allowlist and a monthly spend cap. The [authentication guide](https://docs.rocketverifier.com/authentication) covers each, and [OAuth scopes](https://docs.rocketverifier.com/oauth/scopes) lists what apps can request. | Scope | Endpoints | | --- | --- | | `verify:single` | `POST /v1/verify`, `POST /v1/finder` | | `verify:bulk` | `POST /v1/verify/bulk`, `POST /v1/verify/bulk/upload`, `/preview`, `/confirm` | | `jobs:read` | `GET /v1/jobs` and every `GET /v1/jobs/{jobId}` endpoint | | `jobs:write` | `DELETE /v1/jobs/{jobId}` | | `monitors:read` | `GET /v1/monitors`, `GET /v1/monitors/{monitorId}`, `/runs` | | `monitors:write` | `POST`, `PATCH` and `DELETE` on `/v1/monitors`, and `/run` | | `webhooks:manage` | Every `/v1/webhooks` endpoint except `/events` | | `credits:read` | `GET /v1/credits` | | `account:read` | `GET /v1/me` for OAuth tokens. API keys can always call it. | ## Choose a result version The `RocketVerifier-Version` header picks how catch-all addresses map onto `status`. With `2026-11-01`, a catch-all address is `risky`. With `2025-01-01`, it is `unknown`. Without the header, the key's own version applies, and keys created from November 2026 use `2026-11-01`. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "RocketVerifier-Version: 2026-11-01" \ -H "Content-Type: application/json" \ -d '{"email": "maya@northwind.io"}' ``` The header applies to `POST /v1/verify`, job results and job downloads. [Result versions](https://docs.rocketverifier.com/versioning) explains when to move. ## Retry safely with Idempotency-Key An `Idempotency-Key` header makes a write safe to retry: the same key within 24 hours returns the first response and never charges again. Use any unique string, such as a UUID. - **Accepted on:** `POST /v1/verify`, `POST /v1/verify/bulk` and `POST /v1/verify/bulk/upload`. - **Scope:** keys are stored per account, so two accounts never collide. - **Store unavailable:** a call with a key gets `503 idempotency_unavailable` instead of running unprotected. Retry it, or drop the header. The Node.js and Python SDKs send a fresh key on every write, so their automatic retries never double charge. ## Handle errors Every error, on every endpoint, has the same shape. Branch on `error.code`, show `error.message` to people and read `error.details` for context. Error body: ```json { "error": { "code": "insufficient_credits", "message": "Need 1000 credits, have 640", "details": { "required": 1000, "available": 640 } } } ``` | Status | Typical codes | Meaning | | --- | --- | --- | | 400 | `no_emails`, `job_not_complete`, `invalid_domain` | The request is well formed but cannot run. | | 401 | `unauthorized`, `api_key_expired`, `invalid_token` | The credential is missing, wrong, revoked or expired. | | 402 | `insufficient_credits`, `api_key_spend_cap_reached` | The balance or the key's monthly cap does not cover the charge. | | 403 | `insufficient_scope`, `insufficient_credits`, `sandbox_key_restricted`, `ip_not_allowed`, `account_suspended` | The credential cannot make this call. A zero balance is refused here, before any work runs. | | 404 | `not_found` | The resource does not exist or belongs to another account. | | 409 | `job_not_cancellable`, `job_not_awaiting_confirmation` | The resource changed state. | | 422 | `validation_error` | The body or a parameter failed validation. `details.errors` lists each problem. | | 429 | `rate_limited`, `daily_limit_reached` | Slow down. Wait for `Retry-After` seconds. | | 503 | `maintenance`, `idempotency_unavailable`, `service_unavailable` | Retry after a short wait. | The [errors reference](https://docs.rocketverifier.com/errors) lists every code with the fix. ## Stay within rate limits Limits are counted per minute over a sliding window, per account (organization keys share one bucket per organization). Every response carries the current state: | Header | Meaning | | --- | --- | | `X-RateLimit-Limit` | Requests allowed per minute. | | `X-RateLimit-Remaining` | Requests left in the current window. | | `X-RateLimit-Reset` | Unix time when the oldest request leaves the window. | | `Retry-After` | On `429` only: seconds to wait. | Free and trial accounts get 30 requests per minute, pay as you go accounts 300, and subscriptions 600. Calls without a key get 5 per minute per IP address. A key can carry its own limit. [Rate limits](https://docs.rocketverifier.com/rate-limits) has the details and retry patterns. ## Paginate lists List endpoints take `page` (starting at 1) and `limit`, and return `total`, `page`, `limit` and `has_more`. Request the next page while `has_more` is `true`. | Endpoint | Default `limit` | Max `limit` | | --- | --- | --- | | `GET /v1/jobs` | 20 | 100 | | `GET /v1/jobs/{jobId}/results` | 100 | 1,000 | | `GET /v1/webhooks/{webhookId}/logs` | 50 | 100 | | `GET /v1/monitors/{monitorId}/runs` | 20 | 100 | `GET /v1/webhooks` and `GET /v1/monitors` return the full list as an array. To export every result of a job in one response, use [the download endpoint](https://docs.rocketverifier.com/api/batch#download-results) instead of paging. ## Trace a request Every response carries an `X-Request-ID` header. Send your own (up to 128 characters) to follow a call through your logs, and include it when you contact support. ## Check API status `GET /v1/status` returns the health of the API and its components. It needs no key. `GET /v1/status` cURL: ```bash curl https://api.rocketverifier.com/v1/status ``` Response 200: ```json { "status": "healthy", "version": "1.1.0", "uptime_seconds": 86412.37, "timestamp": "2026-11-11T09:42:17.208114+00:00", "components": [ { "name": "database", "status": "healthy", "latency_ms": 3.12, "details": null }, { "name": "redis", "status": "healthy", "latency_ms": 0.84, "details": null }, { "name": "verification_nodes", "status": "healthy", "latency_ms": null, "details": "12/12 healthy" }, { "name": "engine", "status": "healthy", "latency_ms": null, "details": null }, { "name": "worker_queue", "status": "healthy", "latency_ms": null, "details": "4 queued jobs" } ], "sandbox_domain": "sandbox.rocketverifier.com", "docs_url": "https://docs.rocketverifier.com" } ``` | Field | Type | Description | | --- | --- | --- | | `status` | enum | `degraded` when a core component is unhealthy, no node is healthy, or the engine is in maintenance. one of `healthy`, `degraded` | | `version` | string | | | `uptime_seconds` | number | | | `timestamp` | string (date-time) | | | `components` | array of objects | | | `components.name` | enum | one of `database`, `redis`, `verification_nodes`, `engine`, `worker_queue` | | `components.status` | enum | one of `healthy`, `degraded`, `unhealthy`, `maintenance`, `unknown` | | `components.latency_ms` | number or null | Round trip time, for the database and Redis. | | `components.details` | string or null | Context such as `12/12 healthy` for the node fleet or the queue depth. | | `sandbox_domain` | string | | | `docs_url` | string | | `status` is `degraded` when the database or Redis is unhealthy, when no verification node is healthy, or while the engine is in maintenance. An `engine` component with status `maintenance` explains what is paused in `details`. ## Every endpoint ### Verification | Method | Path | What it does | | --- | --- | --- | | POST | [`/v1/verify`](https://docs.rocketverifier.com/api/verify) | Verify one address in real time. | | POST | [`/v1/verify/bulk`](https://docs.rocketverifier.com/api/batch#create-a-bulk-job) | Start a bulk job from a JSON list of up to 100,000 addresses. | | POST | [`/v1/verify/bulk/upload`](https://docs.rocketverifier.com/api/bulk-upload) | Start a bulk job from a CSV, TSV, TXT or XLSX file or a URL. | | POST | [`/v1/verify/bulk/{jobId}/preview`](https://docs.rocketverifier.com/api/bulk-upload#get-the-free-list-health-preview) | Read the free list health preview of an upload. | | POST | [`/v1/verify/bulk/{jobId}/confirm`](https://docs.rocketverifier.com/api/bulk-upload#confirm-and-start-the-job) | Charge and start a previewed upload. | | GET | [`/v1/jobs`](https://docs.rocketverifier.com/api/batch#list-jobs) | List your bulk jobs. | | GET | [`/v1/jobs/{jobId}`](https://docs.rocketverifier.com/api/batch#get-job-status) | Get a job's status and counters. | | GET | [`/v1/jobs/{jobId}/progress`](https://docs.rocketverifier.com/api/batch#track-progress) | Poll progress, throughput and ETA. | | GET | [`/v1/jobs/{jobId}/results`](https://docs.rocketverifier.com/api/batch#read-results-page-by-page) | Page through per-address results. | | GET | [`/v1/jobs/{jobId}/download`](https://docs.rocketverifier.com/api/batch#download-results) | Download every result as CSV or JSON. | | DELETE | [`/v1/jobs/{jobId}`](https://docs.rocketverifier.com/api/batch#cancel-a-job) | Cancel a job and refund what was not processed. | | POST | [`/v1/finder`](https://docs.rocketverifier.com/api/finder) | Find an address from a name and a company domain. | ### Automation | Method | Path | What it does | | --- | --- | --- | | POST | [`/v1/monitors`](https://docs.rocketverifier.com/api/monitors#create-a-monitor) | Create a list health or domain authentication monitor. | | GET | [`/v1/monitors`](https://docs.rocketverifier.com/api/monitors#list-get-update-and-delete-monitors) | List monitors. | | GET | [`/v1/monitors/{monitorId}`](https://docs.rocketverifier.com/api/monitors#list-get-update-and-delete-monitors) | Get a monitor and its latest result. | | PATCH | [`/v1/monitors/{monitorId}`](https://docs.rocketverifier.com/api/monitors#list-get-update-and-delete-monitors) | Update, pause or resume a monitor. | | DELETE | [`/v1/monitors/{monitorId}`](https://docs.rocketverifier.com/api/monitors#list-get-update-and-delete-monitors) | Delete a monitor. | | POST | [`/v1/monitors/{monitorId}/run`](https://docs.rocketverifier.com/api/monitors#run-a-monitor-now) | Run a monitor now. | | GET | [`/v1/monitors/{monitorId}/runs`](https://docs.rocketverifier.com/api/monitors#read-run-history) | Read a monitor's run history. | | GET | [`/v1/webhooks/events`](https://docs.rocketverifier.com/api/webhooks#list-event-types) | List the events you can subscribe to. | | POST | [`/v1/webhooks`](https://docs.rocketverifier.com/api/webhooks) | Register a webhook endpoint. | | GET | [`/v1/webhooks`](https://docs.rocketverifier.com/api/webhooks#list-get-update-and-delete-webhooks) | List webhook endpoints. | | GET | [`/v1/webhooks/{webhookId}`](https://docs.rocketverifier.com/api/webhooks#list-get-update-and-delete-webhooks) | Get one endpoint. | | PATCH | [`/v1/webhooks/{webhookId}`](https://docs.rocketverifier.com/api/webhooks#list-get-update-and-delete-webhooks) | Update, pause or resume an endpoint. | | DELETE | [`/v1/webhooks/{webhookId}`](https://docs.rocketverifier.com/api/webhooks#list-get-update-and-delete-webhooks) | Delete an endpoint. | | POST | [`/v1/webhooks/{webhookId}/test`](https://docs.rocketverifier.com/api/webhooks#send-a-test-event) | Send a signed test event. | | GET | [`/v1/webhooks/{webhookId}/logs`](https://docs.rocketverifier.com/api/webhooks#read-delivery-logs) | Read delivery attempts. | | POST | [`/v1/webhooks/{webhookId}/rotate-secret`](https://docs.rocketverifier.com/api/webhooks#rotate-the-signing-secret) | Issue a new signing secret. | ### Tools and account | Method | Path | What it does | | --- | --- | --- | | GET | [`/v1/tools/mx-lookup`](https://docs.rocketverifier.com/api/domain#look-up-mx-records) | MX records for a domain. | | GET | [`/v1/tools/disposable-check`](https://docs.rocketverifier.com/api/domain#check-for-disposable-domains) | Is a domain or address disposable. | | GET | [`/v1/tools/domain-auth`](https://docs.rocketverifier.com/api/domain#check-spf-dkim-and-dmarc) | SPF, DKIM and DMARC with a score. | | GET | [`/v1/tools/blacklist-monitor`](https://docs.rocketverifier.com/api/domain#check-dns-blacklists) | DNS blacklist listings for a domain or IP. | | POST | [`/v1/tools/verify-free`](https://docs.rocketverifier.com/api/domain#run-a-free-test-lookup) | Free syntax, MX and disposable lookup. | | GET | [`/v1/tools/activity/{email}`](https://docs.rocketverifier.com/api/domain#read-your-verification-history-for-an-address) | Your own verification history of an address. | | GET | [`/v1/credits`](https://docs.rocketverifier.com/api/credits) | Credit balance and usage. | | GET | [`/v1/me`](https://docs.rocketverifier.com/api/account) | The account behind the credential. | | GET | [`/v1/status`](#check-api-status) | API health. | ## Use an SDK The official SDKs wrap every endpoint above with typed results, retries on `429` and automatic idempotency keys. - [Node.js SDK](https://docs.rocketverifier.com/sdks/nodejs) `npm install @rocketverifier/sdk` - [Python SDK](https://docs.rocketverifier.com/sdks/python) `pip install rocketverifier` - [CLI](https://docs.rocketverifier.com/sdks/cli) Verify addresses and lists from your terminal. - [MCP server](https://docs.rocketverifier.com/mcp) Give Claude, Cursor and other assistants the same tools. ## Frequently asked questions ### Is there a test mode? Yes. Sandbox keys start with `rv_test_` and return fixed results for `@sandbox.rocketverifier.com` addresses on every verification endpoint, without spending credits. Live keys start with `rv_live_`. ### Can I send the API key in an X-API-Key header? No. Every `/v1` endpoint reads the key from `Authorization Bearer` only. Requests that send the key any other way get `401 unauthorized`. ### How do I avoid double charges when I retry? Send an `Idempotency-Key` header on `POST /v1/verify`, `POST /v1/verify/bulk` and `POST /v1/verify/bulk/upload`. A retry with the same key within 24 hours returns the original response and charges nothing. The official SDKs add one to every write automatically. ### Which endpoints work without an API key? `GET /v1/status`, `GET /v1/webhooks/events` and the lookup tools under `/v1/tools` (except activity history). Calls without a key are limited to 5 per minute per IP address. --- # Verify an email Source: https://docs.rocketverifier.com/api/verify Endpoint: `POST https://api.rocketverifier.com/v1/verify` (OAuth scope `verify:single`) > Send one address in the JSON body. You get back a status (deliverable, undeliverable, risky or unknown), the sub_status that explains it, a 0 to 100 score and the evidence behind the verdict. Most answers arrive in under half a second; a live SMTP check takes 1 to 3 seconds. Each result costs 1 credit and unknown results are free. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "maya@northwind.io"}' ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); const result = await rv.verify("maya@northwind.io"); if (result.status === "deliverable") { // safe to send } console.log(result.subStatus, result.score); ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) result = rv.verify("maya@northwind.io") if result.status == "deliverable": pass # safe to send print(result.sub_status, result.score) ``` Response 200: ```json { "email": "maya@northwind.io", "status": "deliverable", "sub_status": "none", "score": 97, "catch_all_verdict": null, "did_you_mean": null, "domain": { "name": "northwind.io", "acceptAll": "no", "disposable": "no", "free": "no" }, "account": { "role": "no", "disabled": "no", "fullMailbox": "no" }, "provider": "google.com", "smtp_provider": "google", "mx_record": "aspmx.l.google.com", "deliverability_tier": "excellent", "verdict_source": "smtp", "retry_after": null, "verified_at": "2026-11-11T09:42:17Z" } ``` ## Request Send a JSON body with the address. Authenticate with an API key, or with an OAuth access token that has the `verify:single` scope. - `Authorization` (string, required): `Bearer `. See [authentication](https://docs.rocketverifier.com/authentication). - `Idempotency-Key` (string): Any unique string, such as a UUID. Retrying with the same key within 24 hours returns the original result without charging again. - `RocketVerifier-Version` (string): `2026-11-01` or `2025-01-01`. Picks how catch-all results map onto `status`. Keys created from November 2026 default to `2026-11-01`. See [result versions](https://docs.rocketverifier.com/versioning). **Body** | Field | Type | Description | | --- | --- | --- | | `email` | string | The email address to verify required | | `timeout` | integer | Seconds to wait for the mail server. Values above 30 are capped at 30. A check that runs out of time returns `unknown` and is not charged. 3 to 60; default 10 | ## Response A `200` response is a single result object. Branch on `status`, read `sub_status` for the reason, and use the rest for segmenting, audits and debugging. | Field | Type | Description | | --- | --- | --- | | `email` | string | The address as verified, trimmed and with a lowercased domain. | | `status` | enum | The field to branch on. `deliverable`: the mail server confirmed the mailbox. `undeliverable`: the address will bounce or is disposable. `risky`: it accepts mail but carries a risk such as a catch-all domain, role address, full mailbox or trap signals. `unknown`: no conclusive answer, never charged. With result version `2025-01-01`, catch-all addresses are reported as `unknown` instead of `risky`. one of `deliverable`, `undeliverable`, `risky`, `unknown` | | `reason` | enum | Legacy reason code derived from `sub_status`. Kept for older integrations. Use `sub_status` in new code. one of `accepted_email`, `rejected_email`, `invalid_syntax`, `invalid_domain`, `no_mx_record`, `disposable_email`, `role_based`, `catch_all`, `timeout`, `blocked`, `account_disabled`, `mailbox_full`, `spam_trap`, `known_complainer`, `suppressed`, `toxic`, `unknown` | | `sub_status` | enum | The precise reason behind `status`. See the sub_status reference for what each value means and costs. one of `none`, `alias`, `forwarder`, `mailbox_not_found`, `account_disabled`, `does_not_accept_mail`, `invalid_syntax`, `invalid_domain`, `disposable`, `catch_all`, `role_based`, `mailbox_full`, `possible_trap`, `toxic`, `do_not_mail`, `accepts_then_bounces`, `privacy_relay`, `parked_domain`, `possible_typo`, `dns_error`, `greylisted`, `blocked`, `smtp_timeout`, `no_connect`, `smtp_unavailable` | | `catch_all_verdict` | enum or null | Send recommendation for this exact address when the domain accepts every address. Null for other domains. one of `send_safe`, `send_with_caution`, `avoid` | | `verified_at` | string (date-time) or null | When the result was produced, in UTC. Earlier than the request when the result came from cache. | | `domain` | object | Facts about the domain. Yes and no values are strings. | | `domain.name` | string | The domain part of the address. | | `domain.acceptAll` | enum | Whether the domain accepts every address (catch-all). one of `yes`, `no`, `unknown` | | `domain.disposable` | enum | Whether the domain belongs to a disposable inbox provider. one of `yes`, `no` | | `domain.free` | enum | Whether the domain is a free mailbox provider such as Gmail or Outlook.com. one of `yes`, `no` | | `domain.acceptAllConfidence` | integer or null | Confidence that this mailbox is real on a catch-all domain. Set only when `acceptAll` is `yes`. 0 to 100 | | `domain.acceptAllVerdict` | enum or null | Internal catch-all verdict. Prefer the top-level `catch_all_verdict`. one of `send_safe`, `risky_catch_all`, `unlikely` | | `account` | object | Facts about the mailbox. Yes and no values are strings. | | `account.role` | enum | Whether this is a role address such as info@ or admin@. one of `yes`, `no` | | `account.disabled` | enum | Whether the mailbox is disabled. one of `yes`, `no`, `unknown` | | `account.fullMailbox` | enum | Whether the mailbox is over quota. one of `yes`, `no`, `unknown` | | `dns` | object | The mail route found in DNS. | | `dns.type` | enum | Record type used for delivery. one of `MX`, `A`, `CNAME` | | `dns.record` | string or null | The record value, such as the MX host. | | `provider` | string or null | Mailbox provider domain, such as `google.com` or `outlook.com`. | | `score` | integer | Confidence that mail to this address will be delivered. Higher is better. 0 to 100 | | `authentication_score` | integer | How well the domain is set up for sending, from its SPF, DKIM and DMARC records. 0 to 100 | | `deliverability_tier` | enum | The score grouped into a tier for simple segmenting. one of `excellent`, `good`, `fair`, `poor`, `unknown` | | `toxic` | enum | Whether the address is linked to abuse, complaints or bot signups. A string, not a boolean. one of `yes`, `no`, `unknown` | | `abuse` | enum | Whether the address is a known complainer. A string, not a boolean. one of `yes`, `no`, `unknown` | | `spam_trap` | enum | Whether the address matches spam trap signals. A string, not a boolean. one of `yes`, `no` | | `did_you_mean` | string or null | Suggested correction when the domain looks like a typo, such as `gmail.com` for `gmial.com`. | | `activity` | object or null | How often and how consistently your own account has verified this address. | | `activity.verification_count` | integer | How many times your account verified this address in the last 90 days (up to 50). | | `activity.activity_score` | integer | How active the address appears. 0 to 100 | | `activity.stability_score` | integer | How consistent its results have been over time. 0 to 100 | | `evidence` | object or null | The raw checks behind the verdict (DNS, MX, SMTP replies) and, on catch-all domains, the reasoning behind the plausibility score. Use it for audits and debugging. Its shape varies by path, so do not parse it in application logic. | | `smtp_provider` | string or null | Mail system behind the MX records, such as `google`, `microsoft_365`, `outlook_consumer`, `yahoo`, `apple`, `zoho` or `proton`. Null when the MX is not a recognised provider. | | `gateway` | string or null | Security gateway in front of the mailbox provider, such as `proofpoint`, `mimecast` or `barracuda`. | | `mx_found` | boolean or null | Whether the domain publishes MX records or an implicit MX. | | `mx_record` | string or null | Highest priority MX host. | | `catch_all` | object or null | Catch-all details. Null unless the domain accepts every address. | | `catch_all.verdict` | enum or null | Same value as `catch_all_verdict`. one of `send_safe`, `send_with_caution`, `avoid` | | `catch_all.score` | integer or null | Plausibility that this mailbox is real. 0 to 100 | | `catch_all.method` | enum | How the score was reached. one of `pattern`, `heuristic` | | `catch_all.reasons` | array of strings | Plain language reasons behind the score. | | `retry_after` | integer or null | For `unknown` results only. Seconds after which a recheck is likely to get a definite answer. Greylisting servers often say how long to wait. | | `verdict_source` | enum or null | Which step decided the result. one of `cache`, `syntax`, `list`, `dns`, `smtp`, `precheck` | | `engine_version` | string or null | Version of the verification engine and verdict rules that produced the result, such as `2.2`. | > **Warning: Yes and no fields are strings** > > `domain.disposable`, `domain.acceptAll`, `account.role` and similar fields hold `"yes"`, `"no"` or `"unknown"`. The string `"no"` is truthy in JavaScript and PHP, so compare explicitly. ## What to do with each status | status | What to do | Meaning | Cost | | --- | --- | --- | --- | | `deliverable` | Send | The mail server explicitly accepted the mailbox. | 1 credit | | `undeliverable` | Remove | The address will bounce: the mailbox, domain or syntax is invalid, or the address is disposable. | 1 credit | | `risky` | Send with care | The address accepts mail but carries a risk: catch-all domain, role address, full mailbox, trap or abuse signals. | 1 credit | | `unknown` | Retry later | The mail server gave no conclusive answer. Retry after retry_after seconds. | Free | The [reading results guide](https://docs.rocketverifier.com/results) lists all 25 `sub_status` values with their cost, and explains scores, catch-all verdicts and typo suggestions. ## Try it Try the sandbox addresses live at https://docs.rocketverifier.com/api/verify#try-it (no key needed). These fixed results come from `POST /v1/verify`. In bulk jobs, sandbox addresses run through the full engine like any other address. The full list and how to test bulk flows are in [sandbox and testing](https://docs.rocketverifier.com/sandbox). ## Credits - **1 credit** for every `deliverable`, `undeliverable` and `risky` result. - **Free:** `unknown` results, addresses on your own suppression list, sandbox addresses, and retries with the same `Idempotency-Key`. - Organization keys draw from the shared pool first when pooling is on. See [teams](https://docs.rocketverifier.com/teams). ## Errors | Status | `error.code` | When it happens | | --- | --- | --- | | 401 | `unauthorized` | The key is missing, malformed or revoked. | | 401 | `api_key_expired` | The key passed its expiry date. Create a new key or extend it. | | 402 | `insufficient_credits` | The balance ran out while charging this result. | | 402 | `api_key_spend_cap_reached` | This key hit its monthly spend cap. | | 403 | `insufficient_credits` | The balance is zero, so the request is refused before any check runs. | | 403 | `sandbox_key_restricted` | An `rv_test_` key was used on a real address. | | 403 | `insufficient_scope` | The OAuth token lacks `verify:single`. | | 403 | `ip_not_allowed` | The key has an IP allowlist that does not include the caller. | | 422 | `validation_error` | The body is not valid JSON, `email` is missing, or `timeout` is out of range. | | 429 | `rate_limited` | Too many requests. Wait for the `Retry-After` seconds. | Every error uses the same shape. The [errors reference](https://docs.rocketverifier.com/errors) covers each code and how to handle it. Error body: ```json { "error": { "code": "insufficient_credits", "message": "You don't have enough credits for this operation", "details": { "required": 1, "available": 0 } } } ``` ## Frequently asked questions ### Am I charged for unknown results? No. An `unknown` result means the mail server gave no conclusive answer, so it costs nothing. Check again after the number of seconds in `retry_after`. Addresses on your own suppression list are also free. ### How long does a verification take? Most results return in under 400 milliseconds because they are decided by syntax, DNS, list checks or cache. Results that need a live SMTP conversation typically take 1 to 3 seconds. Set `timeout` to cap the wait. ### What should I do with a catch-all result? Read `catch_all_verdict`. Send to `send_safe` addresses, send `send_with_caution` addresses only to engaged segments, and drop `avoid` addresses. The catch-all guide explains how the verdict is reached. ### Can I test without spending credits? Yes. Addresses at `@sandbox.rocketverifier.com` return fixed results without a key or credits. Use them in tests and CI, or try them on this page. ### Are the yes and no fields booleans? No. Fields such as `domain.disposable` and `account.role` are the strings `"yes"`, `"no"` or `"unknown"`. Compare them explicitly, for example `result.domain.disposable === "yes"`. The Node.js and Python SDKs convert them to booleans. --- # Verify emails in bulk Source: https://docs.rocketverifier.com/api/batch Endpoint: `POST https://api.rocketverifier.com/v1/verify/bulk` (OAuth scope `verify:bulk`) > 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. cURL: ```bash 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"] }' ``` Node.js: ```js 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 }); ``` Python: ```python 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) ``` Response 200: ```json { "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](https://docs.rocketverifier.com/api/verify). ## 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. - `Authorization` (string, required): `Bearer `. See [authentication](https://docs.rocketverifier.com/authentication). - `Idempotency-Key` (string): 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** | Field | Type | Description | | --- | --- | --- | | `emails` | array of strings | The addresses to verify. At most 100,000 unique addresses after deduplication. Blank entries and duplicates are dropped and never charged. required | | `name` | string | A label for the job, shown in the dashboard and returned on every job endpoint. | The response confirms what was queued and charged. | Field | Type | Description | | --- | --- | --- | | `job_id` | string | The job id. Use it with every `/jobs/{jobId}` endpoint. | | `total_emails` | integer | Unique addresses queued after deduplication. | | `estimated_time_seconds` | integer | Rough processing estimate. | | `credits_to_use` | integer | Credits charged for the job (0 for sandbox keys). Unknown results are refunded at completion. | | `credits_remaining` | integer | Balance after the charge. | - **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](https://docs.rocketverifier.com/api/bulk-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: ```bash curl https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/progress \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const p = await rv.batch.progress("q3Lw8vR2nK5tY1zA0bC9dE"); console.log(`${p.percent}% done, ETA ${p.etaSeconds}s`); ``` Python: ```python p = rv.batch.progress("q3Lw8vR2nK5tY1zA0bC9dE") print(f"{p.percent}% done, ETA {p.eta_seconds}s") ``` Response 200: ```json { "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" } ``` | Field | Type | Description | | --- | --- | --- | | `job_id` | string | required | | `status` | enum | `ingesting` (an upload is being read), `awaiting_confirmation` (free preview ready, waiting for `/confirm`), `pending`, `processing`, `completed`, `failed`, `cancelled`. required; one of `ingesting`, `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed`, `cancelled` | | `total` | integer | Unique addresses in the job. required | | `processed` | integer | Addresses finished so far. required | | `remaining` | integer | Addresses still to verify. required | | `percent` | number | Progress from 0 to 100, rounded to 2 decimals. required | | `counts` | object | Finished addresses per internal classification (valid, invalid, risky, catch_all, disposable, unknown). required | | `counts_by_status` | object | The same counts grouped into statuses with the `2025-01-01` mapping, so catch-all addresses count as `unknown`. required | | `counts_by_status.deliverable` | integer | | | `counts_by_status.undeliverable` | integer | | | `counts_by_status.risky` | integer | | | `counts_by_status.unknown` | integer | | | `rate_per_minute` | number or null | Addresses finished per minute. Null until known. | | `rate_source` | enum or null | `recent` (about the last 5 minutes) or `average` (since the job started). one of `recent`, `average` | | `eta_seconds` | integer or null | Estimated seconds to completion. 0 once completed, null until known. | | `started_at` | string (date-time) or null | | | `completed_at` | string (date-time) or null | | | `updated_at` | string (date-time) or null | | ## Wait for a job to finish Subscribe a [webhook](https://docs.rocketverifier.com/api/webhooks) 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](https://docs.rocketverifier.com/api/bulk-upload#follow-the-job-lifecycle). | ## Get job status `GET /v1/jobs/{jobId}` returns the job's status and its counters by classification. `GET /v1/jobs/{jobId}` cURL: ```bash curl https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | The job id. | | `name` | string or null | The job name you set. | | `status` | enum | `ingesting` (an upload is being read), `awaiting_confirmation` (free preview ready, waiting for `/confirm`), `pending`, `processing`, `completed`, `failed`, `cancelled`. one of `ingesting`, `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed`, `cancelled` | | `total_emails` | integer | Unique addresses in the job. | | `processed_emails` | integer | Addresses finished so far. | | `valid_count` | integer | Classified `valid` (deliverable). | | `invalid_count` | integer | Classified `invalid` (undeliverable). | | `risky_count` | integer | Classified `risky`. | | `catch_all_count` | integer | On catch-all domains. Reported as `risky` with result version `2026-11-01`, `unknown` with `2025-01-01`. | | `disposable_count` | integer | Disposable addresses (undeliverable). | | `unknown_count` | integer | No conclusive answer. Refunded at completion. | | `progress_percent` | number | Progress from 0 to 100. | | `created_at` | string (date-time) | | | `started_at` | string (date-time) or null | | | `completed_at` | string (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** | Field | Type | Description | | --- | --- | --- | | `page` | integer | Page number, starting at 1. min 1; default 1 | | `limit` | integer | Jobs per page. 1 to 100; default 20 | | `status` | enum | Only jobs in this status. one of `ingesting`, `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed`, `cancelled` | cURL: ```bash curl "https://api.rocketverifier.com/v1/jobs?status=completed&limit=50" \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const page = await rv.batch.listPage({ status: "completed", limit: 50 }); console.log(page.total, page.hasMore); ``` Python: ```python 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. `GET /v1/jobs/{jobId}/results` **Query parameters** | Field | Type | Description | | --- | --- | --- | | `page` | integer | Page number, starting at 1. min 1; default 1 | | `limit` | integer | Results per page. 1 to 1000; default 100 | | `classification` | enum | Only rows with this internal classification. To filter by public status instead, use the `filter` parameter of the download endpoint. one of `valid`, `invalid`, `risky`, `catch_all`, `disposable`, `unknown` | cURL: ```bash curl "https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/results?limit=1000&page=1" \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js for await (const r of rv.batch.iterateResults("q3Lw8vR2nK5tY1zA0bC9dE")) { console.log(r.email, r.classification, r.subStatus); } ``` Python: ```python for r in rv.batch.iter_results("q3Lw8vR2nK5tY1zA0bC9dE"): print(r.email, r.classification, r.sub_status) ``` Response 200: ```json { "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 } ``` | Field | Type | Description | | --- | --- | --- | | `email` | string | The address as submitted. | | `status` | enum | The public status, mapped with the result version in effect. one of `deliverable`, `undeliverable`, `risky`, `unknown` | | `classification` | enum | The internal classification behind `status`. one of `valid`, `invalid`, `risky`, `catch_all`, `disposable`, `unknown` | | `is_valid` | boolean | True when `classification` is `valid`. | | `is_disposable` | boolean | | | `is_catch_all` | boolean | | | `confidence_score` | integer | The 0 to 100 score. | | `sub_status` | enum | The precise reason behind the result. Same values as `sub_status` on `/verify`. one of `none`, `alias`, `forwarder`, `mailbox_not_found`, `account_disabled`, `does_not_accept_mail`, `invalid_syntax`, `invalid_domain`, `disposable`, `catch_all`, `role_based`, `mailbox_full`, `possible_trap`, `toxic`, `do_not_mail`, `accepts_then_bounces`, `privacy_relay`, `parked_domain`, `possible_typo`, `dns_error`, `greylisted`, `blocked`, `smtp_timeout`, `no_connect`, `smtp_unavailable` | | `verified_at` | string (date-time) or null | | `status` follows the [result version](https://docs.rocketverifier.com/versioning) 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** | Field | Type | Description | | --- | --- | --- | | `format` | enum | File format. Ignored when `columns` is set (always CSV). default "csv"; one of `csv`, `json` | | `filter` | enum | 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. one of `deliverable`, `undeliverable`, `risky`, `unknown`, `send_safe` | | `include_original` | boolean | 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. default false | | `columns` | enum | CSV in another provider's column layout, with the closest equivalent values, so spreadsheets and import rules built for that provider keep working. one of `zerobounce`, `bouncer`, `kickbox` | cURL: ```bash curl -o send-safe.csv \ "https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/download?filter=send_safe" \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js // 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" }); ``` Python: ```python 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. CSV header: ```text 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. | Field | Type | Description | | --- | --- | --- | | `email` | string | | | `status` | enum | The public status (JSON only). one of `deliverable`, `undeliverable`, `risky`, `unknown` | | `classification` | enum | one of `valid`, `invalid`, `risky`, `catch_all`, `disposable`, `unknown` | | `is_valid` | boolean | | | `is_disposable` | boolean | | | `is_catch_all` | boolean | | | `is_role_based` | boolean | | | `confidence_score` | integer | | | `sub_status` | string | | | `verified_at` | string or null | | | `did_you_mean` | string | Suggested correction, or an empty string. | | `catch_all_verdict` | string | `send_safe`, `send_with_caution`, `avoid`, or an empty string. | | `catch_all_score` | integer or null | Catch-all plausibility score, when the domain is catch-all. | | `free` | boolean | Free mailbox provider. | | `toxic` | boolean | | | `spam_trap` | boolean | | | `disabled` | boolean | Mailbox disabled. | | `mailbox_full` | boolean | | | `smtp_provider` | string | Mail system behind the MX, or an empty string. | | `mx_record` | string | Highest priority MX host, or an empty string. | | `original` | object 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: ```bash 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. `DELETE /v1/jobs/{jobId}` cURL: ```bash curl -X DELETE https://api.rocketverifier.com/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const { refundedCredits } = await rv.batch.cancel("q3Lw8vR2nK5tY1zA0bC9dE"); ``` Python: ```python result = rv.batch.cancel("q3Lw8vR2nK5tY1zA0bC9dE") print(result.refunded_credits) ``` Response 200: ```json { "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](https://docs.rocketverifier.com/integrations/bounce-guarantee). A `credits.low` or `credits.depleted` [webhook](https://docs.rocketverifier.com/api/webhooks#creditslow-and-creditsdepleted) 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](https://docs.rocketverifier.com/api#handle-errors). ## 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. --- # Upload a list for verification Source: https://docs.rocketverifier.com/api/bulk-upload Endpoint: `POST https://api.rocketverifier.com/v1/verify/bulk/upload` (OAuth scope `verify:bulk`) > POST a file (CSV, TSV, TXT or XLSX, up to 50 MB and 500,000 unique addresses) or a public HTTPS URL to /v1/verify/bulk/upload. Add preview=true to get a free list health estimate first, then confirm to charge 1 credit per unique address and start verification. Without preview, the job is charged and started as soon as the file has been read. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify/bulk/upload \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -F "file=@leads.csv" \ -F "name=October leads" \ -F "email_column=Work Email" \ -F "preview=true" ``` Node.js: ```js import fs from "node:fs"; import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); const upload = await rv.batch.upload({ file: fs.createReadStream("leads.csv"), filename: "leads.csv", name: "October leads", emailColumn: "Work Email", preview: true, }); console.log(upload.jobId, upload.status); // "ingesting" ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) upload = rv.batch.upload( "leads.csv", name="October leads", email_column="Work Email", preview=True, ) print(upload.job_id, upload.status) # "ingesting" ``` Response 202: ```json { "job_id": "Jx3nq0V8cW1sT5bYk2dHfA", "status": "ingesting", "preview": true, "status_url": "/v1/jobs/Jx3nq0V8cW1sT5bYk2dHfA", "progress_url": "/v1/jobs/Jx3nq0V8cW1sT5bYk2dHfA/progress" } ``` File upload is the way to verify a spreadsheet or an export without parsing it yourself. RocketVerifier reads the file, finds the email column, removes duplicates and keeps your original columns for the download. ## Choose upload or JSON Use file upload for files and exports, and [`POST /v1/verify/bulk`](https://docs.rocketverifier.com/api/batch) when your code already holds the addresses. | | File upload | JSON bulk | | --- | --- | --- | | Endpoint | `POST /v1/verify/bulk/upload` | `POST /v1/verify/bulk` | | Input | CSV, TSV, TXT or XLSX file, or an HTTPS URL | JSON array of addresses | | Unique addresses per job | 500,000 | 100,000 | | Free list health preview | Yes, with `preview=true` | No | | Charged | When the file has been read, or at confirm | When the job is created | | Original columns in the download | Yes | No | | Sandbox keys | Not accepted | Accepted with sandbox addresses | Both run the same verification, refund unknown results at completion and share every [job endpoint](https://docs.rocketverifier.com/api/batch#track-progress). ## Upload a file Send `multipart/form-data` with the file in the `file` field. The response is `202` with the job id, and the job starts in `ingesting` while the file is read. - `Authorization` (string, required): `Bearer ` with the `verify:bulk` scope. - `Content-Length` (integer, required): Required for multipart uploads. cURL and the SDKs set it for you. Missing it returns `411 length_required`. - `Idempotency-Key` (string): Any unique string. Retrying with the same key within 24 hours returns the original job instead of a second upload. - `file` (file, required): The list: `.csv`, `.tsv`, `.txt` or `.xlsx`, up to 50 MB. Send exactly one of `file` and `source_url`. - `name` (string): Job name shown in the dashboard and on every job endpoint. Up to 200 characters. - `email_column` (string): Header name (case-insensitive) or 0-based index of the email column. Detected automatically when omitted. - `column_mapping` (string): JSON object such as `{"email": "Work Email"}`. Takes precedence over `email_column`. - `preview` (boolean, default false): `true` stops the job after a free list health preview, and nothing is charged until you [confirm](#confirm-and-start-the-job). - `callback_url` (string): Public HTTPS URL that receives a signed POST when the job completes or fails. See [callbacks](#get-a-callback-when-the-job-finishes). ## Import from a URL Send `application/json` with `source_url` instead of a file. RocketVerifier downloads the file server side over HTTPS, with the same 50 MB and 500,000 address limits. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify/bulk/upload \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source_url": "https://files.northwind.io/exports/leads.csv", "name": "October leads", "column_mapping": {"email": "Work Email"}, "preview": true }' ``` **JSON body** | Field | Type | Description | | --- | --- | --- | | `source_url` | string (uri) | Public HTTPS URL of the file, up to 2,048 characters. Fetched server side, 50 MB max. required | | `name` | string | Job name shown in the dashboard. up to 200 characters | | `column_mapping` | object | The email column, such as `{"email": "Work Email"}` or `{"email": 2}`. A bare header name also works. Detected automatically when omitted. | | `email_column` | string | Header name or 0-based index of the email column. Used when `column_mapping` is not set. | | `preview` | boolean | Stop after a free list health preview and wait for `/confirm`. default false | | `callback_url` | string (uri) | Public HTTPS URL that receives a signed POST when the job completes or fails. | The URL must be public HTTPS. Private, loopback and internal addresses are refused with `400 invalid_source_url`. In the SDKs, pass `sourceUrl` (Node.js) or `source_url` (Python) instead of a file. ## Pick the email column When you do not name the column, RocketVerifier chooses it in this order: 1. A header that is exactly an email header, such as `Email`, `E-mail`, `Email Address` or `Mail`. 2. Any header that contains `email` or `e-mail`. 3. The column with the most email-shaped values in the first rows. A file with no header row works too: the first row is treated as data when it contains an address. A `.txt` file with one address per line needs no header at all. Text files are read as UTF-8, with Latin-1 as the fallback, and the delimiter (comma, semicolon, tab or pipe) is detected automatically. Rows keep up to 200 columns, and every cell keeps up to 1,000 characters. Duplicates within the file are removed case-insensitively before charging, and blank rows are skipped. ## Get the free list health preview `POST /v1/verify/bulk/{jobId}/preview` returns an estimate of the list's quality before you spend a credit. Every row gets syntax, disposable, role, MX, duplicate and suppression checks, and a random sample of the rows that need SMTP (the smaller of 200 addresses and 2% of the list) gets a live SMTP probe. The sample's results are projected across the list. `POST /v1/verify/bulk/{jobId}/preview` cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify/bulk/Jx3nq0V8cW1sT5bYk2dHfA/preview \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js let res = await rv.batch.preview(upload.jobId); while (res.pending) { await new Promise((r) => setTimeout(r, 3000)); res = await rv.batch.preview(upload.jobId); } console.log(res.preview.estimatedBounceRate, res.preview.creditsNeeded); ``` Python: ```python import time res = rv.batch.preview(upload.job_id) while res.pending: time.sleep(3) res = rv.batch.preview(upload.job_id) print(res.preview.estimated_bounce_rate, res.preview.credits_needed) ``` Response 200: ```json { "job_id": "Jx3nq0V8cW1sT5bYk2dHfA", "status": "awaiting_confirmation", "preview": { "computed_at": "2026-11-11T10:31:12.004118+00:00", "total_emails": 48210, "duplicates_removed": 1372, "free_checks": { "syntax_invalid": 212, "no_mx": 388, "disposable": 640, "role_based": 1905, "suppressed": 57, "free_provider": 20114, "resolved_without_smtp": 1297, "needs_smtp": 46913 }, "smtp_sample": { "size": 200, "counts": { "valid": 171, "invalid": 14, "catch_all": 11, "unknown": 4 }, "method": "random sample of SMTP-bound rows, min(200, 2%)" }, "estimated_counts": { "valid": 40109, "invalid": 3918, "catch_all": 2580, "disposable": 640, "unknown": 963 }, "estimated_by_status": { "deliverable": 40109, "undeliverable": 4558, "risky": 2580, "unknown": 963 }, "estimated_bounce_rate": 0.0813, "undeliverable_share": 0.0945, "risky_share": 0.0, "unknown_share": 0.0735, "credits_needed": 48210, "estimated_credits_after_refunds": 47247, "confidence": "high" } } ``` While the file is still being read, the call returns `202` with `preview: null`, and the SDKs report `pending`. Poll every few seconds. Add `?refresh=true` to recompute the preview of a job that is waiting for confirmation, for example after you update your suppression list. | Field | Type | Description | | --- | --- | --- | | `computed_at` | string (date-time) | When the preview was computed. | | `total_emails` | integer | Unique addresses after deduplication. | | `duplicates_removed` | integer | Rows dropped as duplicates. Never charged. | | `free_checks` | object | Counts from the checks run on every row, with no SMTP. | | `free_checks.syntax_invalid` | integer | Addresses with invalid syntax. | | `free_checks.no_mx` | integer | Addresses whose domain has no mail route. | | `free_checks.disposable` | integer | Disposable inbox addresses. | | `free_checks.role_based` | integer | Role addresses such as info@ or sales@. | | `free_checks.suppressed` | integer | Addresses on your suppression lists. | | `free_checks.free_provider` | integer | Addresses at free mailbox providers. | | `free_checks.resolved_without_smtp` | integer | Rows decided without SMTP. | | `free_checks.needs_smtp` | integer | Rows that need a live SMTP check. | | `smtp_sample` | object | The live SMTP probe of a random sample of the rows that need SMTP. | | `smtp_sample.size` | integer | Addresses probed, min(200, 2% of the list). | | `smtp_sample.counts` | object | Outcomes by classification. | | `smtp_sample.method` | string | How the sample was drawn. | | `estimated_counts` | object | Estimated count per classification for the whole list. | | `estimated_by_status` | object | Estimated count per status, with catch-all addresses counted as `risky`. | | `estimated_by_status.deliverable` | integer | | | `estimated_by_status.undeliverable` | integer | | | `estimated_by_status.risky` | integer | | | `estimated_by_status.unknown` | integer | | | `estimated_bounce_rate` | number | Expected hard bounce share if the list were sent as is (0 to 1). | | `undeliverable_share` | number | Expected invalid plus disposable share (0 to 1). | | `risky_share` | number | Expected share classified risky, without catch-all (0 to 1). | | `unknown_share` | number | Expected unknown plus catch-all share (0 to 1). | | `credits_needed` | integer | Credits `/confirm` charges (1 per unique address). | | `estimated_credits_after_refunds` | integer | Expected net cost once unknown results are refunded. | | `confidence` | enum | `high` when no SMTP was needed or the sample has 100 or more addresses. one of `high`, `medium`, `low` | ## Confirm and start the job `POST /v1/verify/bulk/{jobId}/confirm` charges 1 credit per unique address (`preview.credits_needed`) and queues the job. It is safe to retry: a job is never charged twice. `POST /v1/verify/bulk/{jobId}/confirm` cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify/bulk/Jx3nq0V8cW1sT5bYk2dHfA/confirm \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const started = await rv.batch.confirm(upload.jobId); console.log(started.creditsCharged, started.creditsRemaining); ``` Python: ```python started = rv.batch.confirm(upload.job_id) print(started.credits_charged, started.credits_remaining) ``` Response 200: ```json { "job_id": "Jx3nq0V8cW1sT5bYk2dHfA", "status": "pending", "credits_charged": 48210, "credits_remaining": 51790 } ``` From here the job behaves like any bulk job. Track it with [progress](https://docs.rocketverifier.com/api/batch#track-progress), and download results with [`include_original=true`](https://docs.rocketverifier.com/api/batch#download-results) to get your own columns back. To drop a previewed list instead, [cancel the job](https://docs.rocketverifier.com/api/batch#cancel-a-job): nothing was charged, so nothing is lost. ## Get a callback when the job finishes Set `callback_url` and RocketVerifier POSTs a signed `job.completed` or `job.failed` event to that URL for this one job. The upload response then includes `callback_secret` (`whsec_...`), shown only once: store it to verify the signature. Callbacks use the same envelope, headers, signature scheme and retry schedule as [webhooks](https://docs.rocketverifier.com/api/webhooks#verify-the-signature), signed with the job's `callback_secret`. For events on every job, register a webhook once instead. ## Follow the job lifecycle An upload moves through these statuses. Every one of them is visible on [`GET /v1/jobs/{jobId}`](https://docs.rocketverifier.com/api/batch#get-job-status). | Status | What is happening | | --- | --- | | `ingesting` | The file is being downloaded, parsed and deduplicated. Nothing is charged. | | `awaiting_confirmation` | `preview=true` only. The preview is ready and the job waits for `/confirm`. Nothing is charged. | | `pending` | Charged and queued. | | `processing` | Verification is running. | | `completed` | Done. Unknown results are refunded, and webhooks and callbacks fire. | | `failed` | The file could not be used, or the job stopped. A `job.failed` event fires. | | `cancelled` | You cancelled it. | An upload fails while ingesting when the file cannot be read, has no email column, has no addresses, has more than 500,000 unique addresses, or the balance does not cover it once read. A failed upload is never charged. ## Errors | Status | `error.code` | When it happens | | --- | --- | --- | | 400 | `missing_file` | Send exactly one of `file` and `source_url`. | | 400 | `unsupported_file_type` | The file is not `.csv`, `.tsv`, `.txt` or `.xlsx`. | | 400 | `empty_file` | The uploaded file has no bytes. | | 400 | `invalid_column_mapping` | `column_mapping` is not valid JSON or not an object. | | 400 | `invalid_source_url`, `invalid_callback_url` | The URL is not public HTTPS or is longer than 2,048 characters. | | 400 | `invalid_json` | The JSON body is not a JSON object. | | 401 | `unauthorized`, `api_key_expired` | The key is missing, invalid, revoked or expired. | | 402 | `insufficient_credits` | No balance for a job without preview, or the balance does not cover the list at confirm. | | 402 | `api_key_spend_cap_reached` | Confirming would pass this key's monthly spend cap. | | 403 | `sandbox_key_restricted` | Sandbox keys cannot upload files. | | 403 | `insufficient_credits`, `insufficient_scope` | The balance is zero, or the credential lacks `verify:bulk`. | | 404 | `not_found` | No job with this id on your account. | | 409 | `preview_unavailable` | The job was uploaded without `preview=true`. | | 409 | `job_not_awaiting_confirmation` | The job is not waiting for confirmation. `details.status` says where it is. | | 411 | `length_required` | The multipart request has no `Content-Length`. | | 413 | `file_too_large` | The file is larger than 50 MB. | | 415 | `unsupported_media_type` | Use `multipart/form-data` or `application/json`. | | 502 | `storage_unavailable` | The file could not be stored. Retry the upload. | | 503 | `maintenance`, `queue_unavailable` | Uploads are paused briefly. Retry shortly. | Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors). ## Frequently asked questions ### What is the largest file I can upload? 50 MB and 500,000 unique addresses per upload, in CSV, TSV, TXT or XLSX. The JSON endpoint POST /v1/verify/bulk takes up to 100,000 addresses per request. ### Does the list health preview cost credits? No. The preview runs syntax, disposable, role, MX, duplicate and suppression checks on every row, plus a live SMTP probe of a random sample, and charges nothing. You pay only when you confirm. ### How does RocketVerifier find the email column? It picks the column whose header looks like an email header, then any header containing "email", then the column with the most email-shaped values. Set email_column or column_mapping to choose it yourself. ### Can I keep my own columns in the results? Yes. Download with include_original=true and every row starts with your file's original columns, followed by the verification results. ### Can I upload with a sandbox key? No. Sandbox keys cannot upload files. Test bulk flows with POST /v1/verify/bulk and @sandbox.rocketverifier.com addresses instead. --- # Find an email address Source: https://docs.rocketverifier.com/api/finder Endpoint: `POST https://api.rocketverifier.com/v1/finder` (OAuth scope `verify:single`) > Send a first name, last name and company domain to POST /v1/finder. RocketVerifier ranks the likely address patterns, verifies the candidates live and returns the best address with a 0 to 100 confidence and the pattern it follows. You pay 1 credit per candidate check with a definite answer, at most 4 per search, and unknown checks are free. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/finder \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"first_name": "Maya", "last_name": "Patel", "domain": "northwind.io"}' ``` Node.js: ```js const res = await fetch("https://api.rocketverifier.com/v1/finder", { method: "POST", headers: { Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ first_name: "Maya", last_name: "Patel", domain: "northwind.io" }), }); const found = await res.json(); if (found.status === "found") console.log(found.email, found.confidence); ``` Python: ```python import os import requests res = requests.post( "https://api.rocketverifier.com/v1/finder", headers={"Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}"}, json={"first_name": "Maya", "last_name": "Patel", "domain": "northwind.io"}, timeout=30, ) found = res.json() if found["status"] == "found": print(found["email"], found["confidence"]) ``` Response 200: ```json { "email": "maya.patel@northwind.io", "confidence": 94, "status": "found", "domain": "northwind.io", "pattern": "first.last", "sub_status": "none", "checked": 1, "alternatives": [], "credits_charged": 1 } ``` The finder turns a name and a company into a verified address. It uses each domain's own naming convention when RocketVerifier has learned it, then confirms the address with the same live verification as [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify). ## Request Send a JSON body with a name and a domain. Authenticate with an API key, or with an OAuth token that has the `verify:single` scope. **Body** | Field | Type | Description | | --- | --- | --- | | `domain` | string | The company domain, such as `northwind.io`. A URL or an address also works: `https://www.northwind.io/about` becomes `northwind.io`. required; up to 253 characters | | `first_name` | string | First name. Send `first_name` or `full_name`. up to 100 characters | | `last_name` | string | Last name. Improves the match on most domains. up to 100 characters | | `full_name` | string | Full name, split into first and last name when `first_name` is not sent. up to 200 characters | Names are normalized before the search: accents are removed and only letters are kept, so `José` becomes `jose` and `O'Brien` becomes `obrien`. With `full_name` and no `first_name`, the first word is the first name and the last word is the last name. ## Response A `200` response means the search finished. Branch on `status`; `email` and `confidence` carry the answer. | Field | Type | Description | | --- | --- | --- | | `email` | string or null | The most likely address. Null for `not_found` and `domain_no_mail`. | | `confidence` | integer | How likely `email` is the person's working mailbox. 0 to 100 | | `status` | enum | `found`: the mail server confirmed the mailbox. `catch_all`: the domain accepts every address, so `email` is the best ranked pattern (confidence up to 75) with `alternatives`. `unverified`: the server would not give a definite answer, so `email` is the best guess (confidence up to 35). `not_found`: every candidate was rejected. `domain_no_mail`: the domain takes no mail. required; one of `found`, `catch_all`, `unverified`, `not_found`, `domain_no_mail` | | `domain` | string | The normalized domain that was searched. required | | `pattern` | string or null | The naming pattern of `email`: `first.last`, `flast`, `first`, `firstlast`, `f.last`, `first_last`, `firstl`, `last.first`, `first-last`, `lastf`, `first.l` or `last`. | | `sub_status` | string or null | The `sub_status` of the deciding check. | | `checked` | integer | Candidate addresses verified. | | `alternatives` | array of objects | Up to three other likely addresses on a catch-all domain. | | `alternatives.email` | string | | | `alternatives.confidence` | integer | 0 to 100 | | `credits_charged` | integer | Credits charged, 1 per candidate check with a definite answer. | ## How the finder works The finder checks the most likely addresses in order and stops as soon as it has an answer, so a search that confirms its first candidate costs 1 credit. 1. **Rank the candidates.** The name is expanded into 12 common company patterns, such as `first.last` (maya.patel), `flast` (mpatel), `first` (maya) and `firstlast` (mayapatel), ordered by how often companies use them. Patterns that need a last name are skipped without one. When RocketVerifier has learned this domain's own pattern, that pattern goes first. 2. **Verify in order.** Up to 4 candidates are verified live. A rejected mailbox moves on to the next candidate. 3. **Stop early.** The search stops at the first confirmed mailbox, at a catch-all domain (more probes prove nothing there), at a domain that takes no mail, or at a server that will not answer. | `status` | What it means | What to do | | --- | --- | --- | | `found` | The mail server confirmed the mailbox. `confidence` is the verification score. | Use the address. | | `catch_all` | The domain accepts every address. `email` is the best ranked pattern, with up to three `alternatives`. Confidence is at most 75. | Use it for engaged outreach, or confirm the address another way first. | | `unverified` | The server blocked, greylisted or timed out. `email` is the best guess. Confidence is at most 35. | Try again later. | | `not_found` | Every candidate was rejected. | No address to use. | | `domain_no_mail` | The domain has no mail route, does not accept mail, failed DNS or is disposable. `sub_status` says which. | Check the domain. | ## Credits - **1 credit per candidate check with a definite answer**, the same price as the check through `POST /v1/verify`. - **At most 4 checks per search**, and never more checks than your balance covers. - **Free:** checks that return `unknown`, addresses on your own suppression list, and sandbox searches. `credits_charged` in the response says what the search cost. The balance must hold at least 1 credit to start a search. ## Limits The finder has its own limits on top of your [account rate limit](https://docs.rocketverifier.com/rate-limits): | Limit | Value | | --- | --- | | Searches per minute, per account | 20 | | Candidate checks per minute, per account | 40 | | Time per search | 25 seconds | When the check budget runs out partway through a search, the finder returns what it knows as `unverified`. When it runs out before the first check, the call returns `429 rate_limited`. ## Test with the sandbox With an `rv_test_` sandbox key, search the domain `sandbox.rocketverifier.com`. The finder returns the top ranked pattern as `found` with confidence 95, checks nothing live and charges nothing. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/finder \ -H "Authorization: Bearer $ROCKETVERIFIER_TEST_KEY" \ -H "Content-Type: application/json" \ -d '{"first_name": "Maya", "last_name": "Patel", "domain": "sandbox.rocketverifier.com"}' ``` Sandbox keys cannot search other domains, and live keys cannot search the sandbox domain. Both return `403 sandbox_key_restricted`. More in [sandbox and testing](https://docs.rocketverifier.com/sandbox). ## Errors | Status | `error.code` | When it happens | | --- | --- | --- | | 400 | `invalid_domain` | `domain` is not a domain name such as `northwind.io`. | | 400 | `invalid_name` | The first name has no letters. | | 401 | `unauthorized`, `api_key_expired` | The key is missing, invalid, revoked or expired. | | 402 | `insufficient_credits` | The balance ran out while charging the search. | | 402 | `api_key_spend_cap_reached` | This key hit its monthly spend cap. | | 403 | `insufficient_credits` | The balance is zero. | | 403 | `sandbox_key_restricted` | A sandbox key searched a real domain, or a live key searched the sandbox domain. | | 403 | `insufficient_scope` | The OAuth token lacks `verify:single`. | | 422 | `validation_error` | `domain` is missing, or neither `first_name` nor `full_name` was sent. | | 429 | `rate_limited` | More than 20 searches or 40 candidate checks in a minute. | | 500 | `finder_failed` | The search could not be completed. Retry it. | Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors). ## Frequently asked questions ### How much does a search cost? 1 credit for each candidate address that got a definite answer, at most 4 per search. A search that confirms its first candidate costs 1 credit, and checks that come back unknown are free. ### What does a catch_all status mean? The domain accepts mail for every address, so no mail server can confirm one mailbox. The finder returns the best ranked pattern with a confidence of up to 75 and up to three alternatives. ### Do I need the last name? Only first_name (or full_name) is required, but a last name unlocks the most common company patterns such as first.last and flast, so send it whenever you have it. ### Can I test the finder for free? Yes. With an rv_test_ sandbox key and the domain sandbox.rocketverifier.com, the finder returns the top pattern as found with confidence 95 and charges nothing. --- # Monitor list health and domain authentication Source: https://docs.rocketverifier.com/api/monitors Endpoint: `POST https://api.rocketverifier.com/v1/monitors` (OAuth scope `monitors:write`) > A monitor re-checks something on a daily or weekly schedule and alerts you when it gets worse. A list_health monitor re-verifies up to 5,000 addresses and alerts when the invalid plus risky share rises. A domain_auth monitor checks a sending domain's SPF, DKIM, DMARC and DNS blacklist listings for free and alerts on any regression. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/monitors \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "northwind.io sending domain", "type": "domain_auth", "domain": "northwind.io", "frequency": "daily", "alert_threshold": 10 }' ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); const monitor = await rv.monitors.create({ name: "northwind.io sending domain", type: "domain_auth", domain: "northwind.io", frequency: "daily", alertThreshold: 10, }); console.log(monitor.id, monitor.nextRunAt); ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) monitor = rv.monitors.create( name="northwind.io sending domain", type="domain_auth", domain="northwind.io", frequency="daily", alert_threshold=10, ) print(monitor.id, monitor.next_run_at) ``` Response 200: ```json { "id": "mN4xQ8rT2vB6yK1pZ7cW3a", "name": "northwind.io sending domain", "type": "domain_auth", "frequency": "daily", "domain": "northwind.io", "email_count": 0, "alert_threshold": 10, "is_active": true, "last_run_at": null, "next_run_at": "2026-11-11T09:42:17.208114+00:00", "last_result": null, "created_at": "2026-11-11T09:42:17.208114+00:00" } ``` Monitors catch deliverability problems before your campaigns do. Each run compares its result with the previous one, and a regression fires a signed [`monitor.alert` webhook](#get-alerts-by-webhook). ## Choose a monitor type | | `list_health` | `domain_auth` | | --- | --- | --- | | Checks | Re-verifies up to 5,000 addresses | SPF, DKIM, DMARC and DNS blacklist listings of one domain | | Needs | `emails` | `domain` | | Alerts when | The invalid plus risky share rises by `alert_threshold` percentage points or more | A record disappears, the authentication score drops by `alert_threshold` points or more, or the domain's mail servers get blacklisted | | Cost | 1 credit per unique address per run, unknown results refunded | Free | ## Create a monitor `POST /v1/monitors` creates a monitor that runs within 10 minutes and then on its schedule. It needs the `monitors:write` scope. **Body** | Field | Type | Description | | --- | --- | --- | | `name` | string | A label for the monitor. required; up to 200 characters | | `type` | enum | `list_health` re-verifies a list; `domain_auth` checks a sending domain. required; one of `list_health`, `domain_auth` | | `frequency` | enum | How often the monitor runs. default "weekly"; one of `daily`, `weekly` | | `domain` | string or null | Required for `domain_auth`. The sending domain to check. | | `emails` | array of strings | Required for `list_health`. Up to 5,000 addresses, stored lowercased. | | `alert_threshold` | integer | `list_health`: alert when the invalid plus risky share rises by at least this many percentage points since the last run. `domain_auth`: alert when the authentication score drops by at least this many points. 1 to 100; default 5 | For a list, send the addresses in `emails`: cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/monitors \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Newsletter subscribers", "type": "list_health", "emails": ["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"], "frequency": "weekly", "alert_threshold": 5 }' ``` Node.js: ```js const monitor = await rv.monitors.create({ name: "Newsletter subscribers", type: "list_health", emails: ["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"], frequency: "weekly", alertThreshold: 5, }); ``` Python: ```python monitor = rv.monitors.create( name="Newsletter subscribers", type="list_health", emails=["maya@northwind.io", "devon@northwind.io", "ops@harbor.dev"], frequency="weekly", alert_threshold=5, ) ``` Addresses are trimmed and lowercased, and each must pass a basic syntax check. A list with an invalid address returns `400 invalid_emails` with up to 10 of them in `details.invalid_sample`. ## Read the monitor object Every monitor endpoint returns this object. `last_result` holds the latest finished result. | Field | Type | Description | | --- | --- | --- | | `id` | string | | | `name` | string | | | `type` | enum | one of `list_health`, `domain_auth` | | `frequency` | enum | one of `daily`, `weekly` | | `domain` | string or null | The checked domain (`domain_auth`). | | `email_count` | integer | Addresses on the list (`list_health`). | | `alert_threshold` | integer | | | `is_active` | boolean | False while paused. | | `last_run_at` | string (date-time) or null | | | `next_run_at` | string (date-time) or null | | | `last_result` | object or null | The latest finished result. See the monitors page for its shape per type. | | `created_at` | string (date-time) | | ### Domain authentication results A `domain_auth` run records the domain's authentication setup and its blacklist status. last_result (domain_auth): ```json { "domain": "northwind.io", "has_spf": true, "has_dmarc": true, "has_dkim": true, "spf_record": "v=spf1 include:_spf.google.com ~all", "dmarc_policy": "quarantine", "authentication_score": 100, "deliverability_tier": "excellent", "is_blacklisted": false, "blacklist_listings": [], "blacklist_checked_ips": ["142.250.153.26", "142.250.153.27"], "checked_at": "2026-11-11T09:50:25.118034+00:00" } ``` ### List health results A `list_health` run re-verifies the list as a bulk job on the priority lane. While the job runs, the run's result is a marker with the `job_id`. When the job completes, the run gets the summary below, and the summary becomes `last_result`. Running: ```json { "status": "running", "job_id": "Vt2kP9wL4sX8nC1bR6mQ0e", "total": 3, "started_at": "2026-11-11T09:50:25.118034+00:00" } ``` last_result (list_health): ```json { "total": 4820, "counts": { "valid": 4310, "invalid": 212, "risky": 96, "catch_all": 151, "disposable": 9, "unknown": 42 }, "bounce_rate_equivalent": 6.4, "credits_used": 4778, "job_id": "Vt2kP9wL4sX8nC1bR6mQ0e", "checked_at": "2026-11-11T10:05:25.402871+00:00" } ``` `bounce_rate_equivalent` is the share of the list classified `invalid` or `risky`, in percent. The full results of each run are in the job: read them with the [bulk job endpoints](https://docs.rocketverifier.com/api/batch#read-results-page-by-page). ## When alerts fire A run alerts when it is worse than the previous finished run. The first run alerts only on problems that already exist. - **`domain_auth`:** SPF, DMARC or DKIM was present and is gone; the authentication score dropped by `alert_threshold` points or more; or the domain's mail servers are newly listed on a DNS blacklist. A blacklist listing is `critical`, everything else is `warning`. A first run alerts when the domain is already blacklisted. - **`list_health`:** `bounce_rate_equivalent` rose by `alert_threshold` percentage points or more. A first run alerts when it is already at `alert_threshold` or 20%, whichever is higher. Alert: ```json { "severity": "warning", "reasons": ["DMARC record is no longer present", "Authentication score dropped from 100 to 65"], "current": { "domain": "northwind.io", "has_dmarc": false, "authentication_score": 65 }, "previous": { "domain": "northwind.io", "has_dmarc": true, "authentication_score": 100 } } ``` `current` and `previous` are the full results; they are shortened here. ## List, get, update and delete monitors Read monitors with `monitors:read`, and change them with `monitors:write`. `GET /v1/monitors` Returns every monitor as an array, most recently created first. Add `?type=list_health` or `?type=domain_auth` to filter. `GET /v1/monitors/{monitorId}` Returns one monitor with its latest result. `PATCH /v1/monitors/{monitorId}` Changes any subset of fields. Set `is_active` to `false` to pause the schedule and `true` to resume it. Sending `emails` replaces the whole list. **Body** | Field | Type | Description | | --- | --- | --- | | `name` | string | A label for the monitor. | | `frequency` | enum | one of `daily`, `weekly` | | `is_active` | boolean | `false` pauses the schedule; `true` resumes it. | | `alert_threshold` | integer | 1 to 100 | | `domain` | string | A new domain for `domain_auth` monitors. | | `emails` | array of strings | Replaces the list of a `list_health` monitor (up to 5,000). | `DELETE /v1/monitors/{monitorId}` Deletes the monitor and its run history, and returns `{"success": true, "message": "Monitor deleted"}`. cURL: ```bash curl -X PATCH https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"is_active": false}' ``` Node.js: ```js const all = await rv.monitors.list(); await rv.monitors.update("mN4xQ8rT2vB6yK1pZ7cW3a", { isActive: false }); await rv.monitors.delete("mN4xQ8rT2vB6yK1pZ7cW3a"); ``` Python: ```python monitors = rv.monitors.list() rv.monitors.update("mN4xQ8rT2vB6yK1pZ7cW3a", is_active=False) rv.monitors.delete("mN4xQ8rT2vB6yK1pZ7cW3a") ``` ## Run a monitor now `POST /v1/monitors/{monitorId}/run` runs a monitor immediately and leaves its schedule unchanged. Use it to test a monitor right after you create it. `POST /v1/monitors/{monitorId}/run` cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a/run \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const { result, alert } = await rv.monitors.runNow("mN4xQ8rT2vB6yK1pZ7cW3a"); ``` Python: ```python outcome = rv.monitors.run_now("mN4xQ8rT2vB6yK1pZ7cW3a") print(outcome["result"], outcome["alert"]) ``` A `domain_auth` run finishes in the request and returns its full `result` and any `alert`. A `list_health` run starts a re-verification job, charged like any bulk job, and returns the running marker with the `job_id`. A list health monitor runs one re-verification at a time, so calling run again while one is running returns the same marker. A run that cannot start, for example because the balance does not cover the list, returns `400 run_failed`. | Field | Type | Description | | --- | --- | --- | | `monitor_id` | string | | | `result` | object | The run result, or the running marker of a `list_health` re-verification. | | `alert` | object or null | The alert raised by this run, if any. | ## Read run history `GET /v1/monitors/{monitorId}/runs` lists past runs, most recent first, in pages of up to 100. `GET /v1/monitors/{monitorId}/runs` **Query parameters** | Field | Type | Description | | --- | --- | --- | | `page` | integer | Page number, starting at 1. min 1; default 1 | | `limit` | integer | Runs per page. 1 to 100; default 20 | cURL: ```bash curl "https://api.rocketverifier.com/v1/monitors/mN4xQ8rT2vB6yK1pZ7cW3a/runs?limit=10" \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const { runs, hasMore } = await rv.monitors.runs("mN4xQ8rT2vB6yK1pZ7cW3a", 1, 10); ``` Python: ```python page = rv.monitors.runs("mN4xQ8rT2vB6yK1pZ7cW3a", page=1, limit=10) ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | | | `result` | object | The run's result. A `list_health` run reads `status: running` with its `job_id` until the job completes. | | `changed` | boolean | True when the run found a regression. | | `alert_fired` | boolean | True when a `monitor.alert` webhook was queued. | | `error_message` | string or null | | | `run_at` | string (date-time) | | ## Get alerts by webhook Subscribe a [webhook](https://docs.rocketverifier.com/api/webhooks) to `monitor.alert`. Every alert arrives as a signed event that names the monitor and carries the alert. monitor.alert: ```json { "event_id": "3e8a1c7f-2b4d-4f9e-8a6c-1d5b7e9f0a24", "event": "monitor.alert", "timestamp": "2026-11-11T10:05:26.004211+00:00", "data": { "monitor_id": "mN4xQ8rT2vB6yK1pZ7cW3a", "monitor_name": "northwind.io sending domain", "monitor_type": "domain_auth", "severity": "warning", "reasons": ["DMARC record is no longer present"], "current": { "domain": "northwind.io", "has_dmarc": false, "authentication_score": 65 }, "previous": { "domain": "northwind.io", "has_dmarc": true, "authentication_score": 100 } } } ``` The run's `alert_fired` is `true` once the event is queued. ## Credits - **`domain_auth`:** free. Runs use DNS lookups only. - **`list_health`:** 1 credit per unique address per run, charged when the run starts. Unknown results and addresses on your suppression list are refunded when the run completes. A run the balance cannot cover charges nothing and records an error. Creating and running monitors needs a balance above zero. ## Errors | Status | `error.code` | When it happens | | --- | --- | --- | | 400 | `domain_required` | A `domain_auth` monitor has no `domain`. | | 400 | `emails_required` | A `list_health` monitor has no `emails`. | | 400 | `invalid_emails` | Addresses failed the syntax check. `details.invalid_sample` lists up to 10. | | 400 | `too_many_emails` | More than 5,000 addresses. | | 400 | `no_changes`, `invalid_frequency` | The update sent nothing to change, or an unknown `frequency`. | | 400 | `run_failed` | A run now could not start, for example for lack of credits. | | 401 | `unauthorized`, `api_key_expired` | The key is missing, invalid, revoked or expired. | | 403 | `insufficient_scope` | The credential lacks `monitors:read` or `monitors:write`. | | 403 | `insufficient_credits` | The balance is zero. | | 404 | `not_found` | No monitor with this id on your account. | | 422 | `validation_error` | `name` or `type` is missing, `type` or `frequency` is unknown, or `alert_threshold` is outside 1 to 100. | Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors). ## Frequently asked questions ### Do monitors cost credits? Domain authentication monitors are free. List health runs are charged like a bulk job, 1 credit per unique address, with unknown results refunded when the run completes. ### How soon does a new monitor run? The scheduler checks for due monitors every 10 minutes, so a new monitor runs within 10 minutes and then every day or week. Call POST /v1/monitors/{monitorId}/run to run it immediately. ### How do I get alerts? Subscribe a webhook to the monitor.alert event. Every regression sends a signed event with the reasons and the current and previous results. ### How do I pause a monitor? PATCH the monitor with is_active set to false. Set it back to true to resume the schedule. --- # Receive events with webhooks Source: https://docs.rocketverifier.com/api/webhooks Endpoint: `POST https://api.rocketverifier.com/v1/webhooks` (OAuth scope `webhooks:manage`) > Register an HTTPS endpoint with POST /v1/webhooks and RocketVerifier POSTs a signed JSON event to it for each subscribed event. Verify the X-RocketVerifier-Signature header (an HMAC SHA-256 of the timestamp and the raw body), answer with any 2xx within 10 seconds, and de-duplicate on the event id. Failed deliveries are retried 5 times over about 26 hours. cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/webhooks \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.northwind.io/rocketverifier", "events": ["job.completed", "job.failed", "credits.low"], "name": "Production" }' ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); const hook = await rv.webhooks.create({ url: "https://hooks.northwind.io/rocketverifier", events: ["job.completed", "job.failed", "credits.low"], name: "Production", }); // Shown only once: store it as ROCKETVERIFIER_WEBHOOK_SECRET console.log(hook.secret); ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) hook = rv.webhooks.create( "https://hooks.northwind.io/rocketverifier", events=["job.completed", "job.failed", "credits.low"], name="Production", ) # Shown only once: store it as ROCKETVERIFIER_WEBHOOK_SECRET print(hook.secret) ``` Response 200: ```json { "id": "cm3k9x2v40001qz8l5h7d2f6a", "name": "Production", "url": "https://hooks.northwind.io/rocketverifier", "events": ["job.completed", "job.failed", "credits.low"], "is_active": true, "success_count": 0, "failure_count": 0, "last_triggered_at": null, "last_success_at": null, "last_failure_at": null, "created_at": "2026-11-11T09:42:17.208114+00:00", "secret": "Xq3v...store-this-now", "signature_header": "X-RocketVerifier-Signature", "verification_instructions": "Every delivery is signed. ..." } ``` Webhooks push events to your server the moment they happen, so you never poll for a finished job or a low balance. Every delivery is signed, retried on failure and logged for debugging. ## Create a webhook `POST /v1/webhooks` registers an HTTPS endpoint for one or more events and returns its signing secret. Store the secret straight away: it is shown only in this response. The webhook endpoints need the `webhooks:manage` scope and work at any balance. **Body** | Field | Type | Description | | --- | --- | --- | | `url` | string (uri) | The HTTPS URL that receives deliveries. It must be publicly reachable. required | | `events` | array of strings | The events to deliver. default ["job.completed","job.failed"] | | `name` | string | A label for the endpoint. | | Field | Type | Description | | --- | --- | --- | | `id` | string | | | `name` | string or null | | | `url` | string (uri) | | | `events` | array of strings | The subscribed events. | | `is_active` | boolean | False when paused, or after 10 failed attempts in a row. | | `success_count` | integer | Successful delivery attempts. | | `failure_count` | integer | Failed attempts since the last success. | | `last_triggered_at` | string (date-time) or null | | | `last_success_at` | string (date-time) or null | | | `last_failure_at` | string (date-time) or null | | | `created_at` | string (date-time) | | | `secret` | string | The signing secret, shown only this once. | | `signature_header` | string | The header that carries the signature. default "X-RocketVerifier-Signature" | | `verification_instructions` | string | Plain text instructions with sample verification code. | The URL must use HTTPS and resolve to a public address. Deliveries never follow redirects, so register the final URL. ## List event types There are seven events. `GET /v1/webhooks/events` returns the same list with descriptions and needs no key. | Event | Fires when | | --- | --- | | `job.completed` | A bulk job finishes. | | `job.failed` | A bulk job fails, including uploads that could not be read. | | `credits.low` | A charge leaves 100 credits or fewer, above zero. | | `credits.depleted` | A charge brings the balance to zero. | | `email.verified` | A single verification with a live key finishes, or a connector verifies a new contact. High volume. | | `monitor.alert` | A [monitor](https://docs.rocketverifier.com/api/monitors) finds a regression. | | `integration.sync.completed` | An integration sync, re-check or campaign guard run finishes. | New webhooks subscribe to `job.completed` and `job.failed` when `events` is omitted. ## Verify the signature Every delivery carries an `X-RocketVerifier-Signature` header of the form `t=,v1=`. `v1` is the HMAC SHA-256, keyed with your webhook secret, of the timestamp, a period and the raw request body. To verify a delivery: 1. Read the **raw** body bytes. Never verify JSON you parsed and serialized again. 2. Split the header into `t` and `v1`. 3. Reject the delivery when `t` is more than 300 seconds from your clock. 4. Compute `HMAC_SHA256(secret, t + "." + raw_body)` as hex and compare it with `v1` in constant time. The SDKs do all four steps in one call. Node.js: ```js import express from "express"; import { constructWebhookEvent, WebhookSignatureError } from "@rocketverifier/sdk"; const app = express(); app.post("/rocketverifier", express.raw({ type: "application/json" }), (req, res) => { let event; try { event = constructWebhookEvent( req.body, // Buffer: the raw body req.headers["x-rocketverifier-signature"], process.env.ROCKETVERIFIER_WEBHOOK_SECRET ); } catch (err) { if (err instanceof WebhookSignatureError) return res.status(400).send(err.reason); throw err; } if (event.event === "job.completed") { // queue the download of event.data.job_id } res.sendStatus(204); }); ``` Python: ```python import os from flask import Flask, request from rocketverifier import construct_event, WebhookSignatureError app = Flask(__name__) @app.post("/rocketverifier") def rocketverifier_webhook(): try: event = construct_event( request.get_data(), # the raw body bytes request.headers.get("X-RocketVerifier-Signature", ""), os.environ["ROCKETVERIFIER_WEBHOOK_SECRET"], ) except WebhookSignatureError: return "", 400 if event["event"] == "job.completed": pass # queue the download of event["data"]["job_id"] return "", 204 ``` ### Verify without an SDK The scheme needs only the standard library. Node.js: ```js import crypto from "node:crypto"; export function verifySignature(rawBody, header, secret, toleranceSec = 300) { const parts = Object.fromEntries( String(header || "").split(",").map((p) => p.trim().split("=", 2)) ); const t = parts.t; const v1 = parts.v1 || ""; if (!/^\d+$/.test(t || "")) return false; if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false; const expected = crypto .createHmac("sha256", secret) .update(`${t}.`) .update(rawBody) // Buffer or string, exactly as received .digest("hex"); return ( v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) ); } ``` Python: ```python import hashlib import hmac import time def verify_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool: parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p) t, v1 = parts.get("t", ""), parts.get("v1", "") if not t.isdigit() or abs(time.time() - int(t)) > tolerance: return False expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, v1) ``` ### Delivery headers | Header | Value | | --- | --- | | `X-RocketVerifier-Signature` | `t=,v1=`. Verify this one. | | `X-RocketVerifier-Timestamp` | The same Unix timestamp as `t`. | | `X-RocketVerifier-Event-Id` | The event id, stable across retries. Also `event_id` in the body. | | `X-Webhook-Event` | The event name. | | `X-Webhook-ID` | The id of your webhook endpoint. | | `X-Webhook-Retry` | 0 on the first attempt, then 1 to 5. | | `X-Webhook-Timestamp` | The signing time, as ISO 8601. | | `X-Webhook-Signature` | Legacy `sha256=` HMAC of the body alone, kept for older integrations. | | `User-Agent` | `RocketVerifier-Webhook/1.0` | ## Respond and handle retries Answer with any `2xx` status within 10 seconds. Do the real work in a background queue, so slow processing never turns into a timeout. | Your endpoint returns | What happens | | --- | --- | | `2xx` | Delivered. `failure_count` resets to 0. | | `5xx`, `429`, a timeout or a network error | Retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 24 hours: 6 attempts in all. | | Any other `4xx` | Final. Not retried. | Delivery is at least once. Store each `X-RocketVerifier-Event-Id` and skip ids you have already handled. Job events use a fixed id per job and event, so a repeated `job.completed` for the same job always has the same id. After 10 failed attempts in a row, the endpoint is disabled (`is_active: false`) and receives nothing more. Fix it, then [re-enable it](#list-get-update-and-delete-webhooks) with `is_active: true`, which also resets `failure_count`. ## Read event payloads Every delivery is a JSON envelope with the same four fields. `data` depends on the event. Envelope: ```json { "event_id": "0b7e9c52-6a51-5f0e-9a43-2f1c8d7e4b10", "event": "job.completed", "timestamp": "2026-11-11T10:02:15.480211+00:00", "data": {} } ``` ### job.completed and job.failed Both carry the job's final counters. For `job.failed`, `status` is `failed` and `download_url` is `null`. data: ```json { "job_id": "q3Lw8vR2nK5tY1zA0bC9dE", "status": "completed", "name": "October signups", "total_emails": 1000, "processed_emails": 1000, "valid_count": 842, "invalid_count": 61, "risky_count": 19, "catch_all_count": 48, "disposable_count": 12, "unknown_count": 18, "created_at": "2026-11-11T09:58:02.114Z", "started_at": "2026-11-11T09:58:04.902Z", "completed_at": "2026-11-11T10:02:15.301Z", "download_url": "/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/download" } ``` `download_url` is a path on `https://api.rocketverifier.com`. Call it with your key, as in [download results](https://docs.rocketverifier.com/api/batch#download-results). ### credits.low and credits.depleted `credits.low` fires after every charge that leaves 100 credits or fewer, so expect several while the balance is low. `credits.depleted` fires when a charge brings the balance to zero, and has no `threshold`. data: ```json { "credits_remaining": 84, "threshold": 100, "message": "Your credit balance is low (84 credits remaining)." } ``` ### email.verified Sent after each `POST /v1/verify` with a live key. The values match the [verify response](https://docs.rocketverifier.com/api/verify#response), including the [result version](https://docs.rocketverifier.com/versioning) of that request. data: ```json { "email": "maya@northwind.io", "status": "deliverable", "sub_status": "none", "reason": "accepted_email", "score": 97, "disposable": "no", "accept_all": "no", "catch_all_verdict": null, "provider": "google.com", "did_you_mean": null, "verified_at": "2026-11-11T10:02:15Z" } ``` Events from connectors that verify new contacts carry `email`, `status`, `sub_status`, `score`, `classification`, `disposable`, `accept_all`, `catch_all_verdict` and `verified_at`, plus `source` (the platform), `integration_id`, `source_id`, `contact_id` and `job_id`. ### monitor.alert Names the monitor and carries the alert: `severity` (`warning` or `critical`), the `reasons`, and the `current` and `previous` results. The [monitors page](https://docs.rocketverifier.com/api/monitors#get-alerts-by-webhook) has a full example. ### integration.sync.completed Sent when an integration sync finishes with at least one contact verified or reused. | Field | Meaning | | --- | --- | | `integration_id`, `platform` | Which integration ran. | | `sync_log_id`, `job_id` | The sync log and the verification job behind it. | | `status` | How the run ended, such as `completed`. | | `mode`, `trigger` | `full`, `incremental` or `new_contacts`, and what started the run. | | `counts` | Contacts per classification. | | `changes` | Contacts whose result changed since the last check. | | `reused` | Contacts answered from recent results, at no cost. | | `updated`, `failed` | Contacts written back to the platform, and writes that failed. | | `actions`, `planned` | Actions taken, and actions held for your review. | | `credits_used` | Net credits the run used. | | `completed_at` | When the run finished. | ### test [Test deliveries](#send-a-test-event) use the event name `test`, with `data` set to `{"message": "This is a test webhook from RocketVerifier", "webhook_id": "...", "test": true}`. ## List, get, update and delete webhooks All four need the `webhooks:manage` scope. Secrets are never returned after creation. `GET /v1/webhooks` Returns every endpoint as an array, most recently created first. `GET /v1/webhooks/{webhookId}` Returns one endpoint with its delivery counters. | Field | Type | Description | | --- | --- | --- | | `id` | string | | | `name` | string or null | | | `url` | string (uri) | | | `events` | array of strings | The subscribed events. | | `is_active` | boolean | False when paused, or after 10 failed attempts in a row. | | `success_count` | integer | Successful delivery attempts. | | `failure_count` | integer | Failed attempts since the last success. | | `last_triggered_at` | string (date-time) or null | | | `last_success_at` | string (date-time) or null | | | `last_failure_at` | string (date-time) or null | | | `created_at` | string (date-time) | | `PATCH /v1/webhooks/{webhookId}` Changes any subset of fields. Sending `events` replaces the whole subscription. **Body** | Field | Type | Description | | --- | --- | --- | | `name` | string | A label for the endpoint. | | `url` | string (uri) | A new HTTPS URL. | | `events` | array of strings | Replaces the subscribed events. | | `is_active` | boolean | `false` pauses deliveries; `true` resumes them and resets `failure_count`. | `DELETE /v1/webhooks/{webhookId}` Deletes the endpoint and its delivery logs, and returns `{"success": true, "message": "Webhook deleted"}`. cURL: ```bash curl -X PATCH https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"is_active": true, "events": ["job.completed", "job.failed", "monitor.alert"]}' ``` Node.js: ```js const hooks = await rv.webhooks.list(); await rv.webhooks.update("cm3k9x2v40001qz8l5h7d2f6a", { isActive: true, events: ["job.completed", "job.failed", "monitor.alert"], }); await rv.webhooks.delete("cm3k9x2v40001qz8l5h7d2f6a"); ``` Python: ```python hooks = rv.webhooks.list() rv.webhooks.update( "cm3k9x2v40001qz8l5h7d2f6a", is_active=True, events=["job.completed", "job.failed", "monitor.alert"], ) rv.webhooks.delete("cm3k9x2v40001qz8l5h7d2f6a") ``` ## Send a test event `POST /v1/webhooks/{webhookId}/test` sends a signed `test` event to the endpoint right away and reports how it answered. It costs no credits. The call returns `200` even when the delivery fails, so read `success`. `POST /v1/webhooks/{webhookId}/test` cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/test \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const result = await rv.webhooks.test("cm3k9x2v40001qz8l5h7d2f6a"); console.log(result.success, result.statusCode, result.responseTimeMs); ``` Python: ```python result = rv.webhooks.test("cm3k9x2v40001qz8l5h7d2f6a") print(result.success, result.status_code, result.response_time_ms) ``` Response 200: ```json { "success": true, "message": "Test webhook delivered successfully! Your endpoint responded with status 204.", "status_code": 204, "response_time_ms": 182 } ``` ## Read delivery logs `GET /v1/webhooks/{webhookId}/logs` lists every delivery attempt, newest first, with your endpoint's status code, the error and the duration. Use it to debug failed deliveries. `GET /v1/webhooks/{webhookId}/logs` **Query parameters** | Field | Type | Description | | --- | --- | --- | | `page` | integer | Page number, starting at 1. min 1; default 1 | | `limit` | integer | Attempts per page. 1 to 100; default 50 | | `status` | enum | Only attempts with this outcome. one of `pending`, `success`, `failed`, `retrying` | cURL: ```bash curl "https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/logs?status=failed" \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const { logs } = await rv.webhooks.logs("cm3k9x2v40001qz8l5h7d2f6a", { status: "failed" }); ``` Python: ```python page = rv.webhooks.logs("cm3k9x2v40001qz8l5h7d2f6a", status="failed") ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | | | `event` | string | | | `attempt_number` | integer | 1 for the first attempt, up to 6. | | `status` | enum | one of `pending`, `success`, `failed`, `retrying` | | `status_code` | integer or null | Your endpoint's HTTP status. Null on a timeout or network error. | | `error_message` | string or null | | | `duration_ms` | integer or null | | | `created_at` | string (date-time) | | ## Rotate the signing secret `POST /v1/webhooks/{webhookId}/rotate-secret` issues a new secret and returns it once. The old secret stops working at once, so deploy the new one to your receiver straight away. `POST /v1/webhooks/{webhookId}/rotate-secret` cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/rotate-secret \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js const { secret } = await rv.webhooks.rotateSecret("cm3k9x2v40001qz8l5h7d2f6a"); ``` Python: ```python secret = rv.webhooks.rotate_secret("cm3k9x2v40001qz8l5h7d2f6a")["secret"] ``` ## Errors | Status | `error.code` | When it happens | | --- | --- | --- | | 400 | `invalid_url` | The URL does not use HTTPS. | | 400 | `invalid_events` | An event name is not one of the seven events. | | 400 | `no_changes` | The update sent nothing to change. | | 401 | `unauthorized`, `api_key_expired` | The key is missing, invalid, revoked or expired. | | 403 | `insufficient_scope` | The credential lacks `webhooks:manage`. | | 404 | `not_found` | No webhook with this id on your account. | | 422 | `validation_error` | `url` is missing or a field has the wrong type. | Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors). ## Frequently asked questions ### Why does my signature check fail? Almost always because the body was parsed and re-serialized before verifying. Compute the HMAC over the exact raw bytes you received, for example with express.raw() in Express or request.get_data() in Flask. ### Can the same event arrive twice? Yes. Delivery is at least once, so a retry can arrive after your endpoint already handled the event. Store the X-RocketVerifier-Event-Id header (also event_id in the body) and skip ids you have seen. ### What happens when my endpoint is down? Each delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 24 hours. After 10 failed attempts in a row the endpoint is disabled. Fix it, then PATCH it with is_active set to true. ### I lost my webhook secret. What now? Call POST /v1/webhooks/{webhookId}/rotate-secret. It returns a new secret and the old one stops working at once. ### Which events fire per verification? Only email.verified, after every single verification with a live key and for new contacts verified by connectors that emit it. It is high volume, so subscribe to it only when you need it. --- # Domain and lookup tools Source: https://docs.rocketverifier.com/api/domain Endpoint: `GET https://api.rocketverifier.com/v1/tools/mx-lookup` > The /v1/tools endpoints answer DNS-level questions about a domain for free, with no verification credits. Look up MX records, detect disposable domains, score SPF, DKIM and DMARC, and check DNS blacklists. They work without a key at 5 requests per minute per IP, or at your account's rate limit with one. cURL: ```bash curl "https://api.rocketverifier.com/v1/tools/mx-lookup?domain=northwind.io" ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); // MX lookup and disposable check in one call const domain = await rv.domain.check("northwind.io"); console.log(domain.hasValidMx, domain.mxRecords, domain.disposable); ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) # MX lookup and disposable check in one call domain = rv.domain.check("northwind.io") print(domain.has_valid_mx, domain.mx_records, domain.disposable) ``` Response 200: ```json { "domain": "northwind.io", "has_mx": true, "mx_records": [ { "priority": 1, "host": "aspmx.l.google.com" }, { "priority": 5, "host": "alt1.aspmx.l.google.com" } ], "primary_mx": "aspmx.l.google.com" } ``` The lookup tools answer questions about a domain from DNS and blocklists, in one fast request and without spending credits. They power the free tools on rocketverifier.com and the MCP server, and they are open to your code too. ## Call the tools with or without a key Every tool except activity history works without a key. Anonymous calls are limited to 5 requests per minute per IP address. Send `Authorization: Bearer ` to use your account's [rate limit](https://docs.rocketverifier.com/rate-limits) instead. Anonymous calls are refused with `503 service_unavailable` in the rare moment the rate limiter is unreachable, so retry after a short wait. Every tool accepts a domain or a full address. With an address, the domain after the `@` is used. ## Look up MX records `GET /v1/tools/mx-lookup` returns a domain's MX records in priority order and its primary mail server. A `POST` variant takes the same `domain` query parameter. **Query parameters** | Field | Type | Description | | --- | --- | --- | | `domain` | string | A domain, or an address whose domain is looked up. required | | Field | Type | Description | | --- | --- | --- | | `domain` | string | | | `has_mx` | boolean | True when the domain publishes MX records. | | `mx_records` | array of objects | | | `mx_records.priority` | integer | MX preference. Lower is tried first. | | `mx_records.host` | string | | | `primary_mx` | string or null | The highest priority MX host. | ## Check for disposable domains `GET /v1/tools/disposable-check` says whether a domain or address belongs to a disposable inbox provider, from a continuously updated database of tens of thousands of disposable domains. `POST` takes the same fields as a JSON body. `GET /v1/tools/disposable-check` cURL: ```bash curl "https://api.rocketverifier.com/v1/tools/disposable-check?email=jo@mailinator.com" ``` Response 200: ```json { "email": "jo@mailinator.com", "domain": "mailinator.com", "is_disposable": true, "provider_hint": "disposable" } ``` **Query parameters** | Field | Type | Description | | --- | --- | --- | | `email` | string | An address. Its domain is checked. Takes precedence over `domain`. | | `domain` | string | A domain to check. | | Field | Type | Description | | --- | --- | --- | | `email` | string or null | The address you sent, if any. | | `domain` | string | The domain that was checked. | | `is_disposable` | boolean | | | `provider_hint` | string or null | `disposable` when the domain is disposable, otherwise null. | A request with neither `email` nor `domain` returns `400 missing_input`. ## Check SPF, DKIM and DMARC `GET /v1/tools/domain-auth` reads a domain's SPF, DMARC and DKIM records, scores them from 0 to 100 and returns one fix per missing record. `GET /v1/tools/domain-auth` cURL: ```bash curl "https://api.rocketverifier.com/v1/tools/domain-auth?domain=northwind.io" ``` Response 200: ```json { "domain": "northwind.io", "spf": { "status": "pass", "record": "v=spf1 include:_spf.google.com ~all" }, "dmarc": { "status": "missing", "record": null }, "dkim": { "status": "pass", "selectors": ["google"] }, "score": 65, "recommendations": ["Publish a DMARC policy at _dmarc.{domain}."] } ``` The score adds 35 points for SPF, 35 for DMARC and 30 for DKIM. DKIM is found on the selectors `default`, `google`, `selector1`, `selector2`, `k1`, `s1` and `mail`, so a key on another selector reads as `missing`. To watch these records over time and get alerted when one disappears, create a [domain authentication monitor](https://docs.rocketverifier.com/api/monitors). | Field | Type | Description | | --- | --- | --- | | `domain` | string | | | `spf` | object | | | `spf.status` | enum | one of `pass`, `missing` | | `spf.record` | string or null | The `v=spf1` TXT record. | | `dmarc` | object | | | `dmarc.status` | enum | one of `pass`, `missing` | | `dmarc.record` | string or null | The `v=DMARC1` record at `_dmarc.`. | | `dkim` | object | | | `dkim.status` | enum | one of `pass`, `missing` | | `dkim.selectors` | array of strings | Selectors with a published DKIM key. | | `score` | integer | SPF 35, DMARC 35, DKIM 30. 0 to 100 | | `recommendations` | array of strings | One fix per missing record. | ## Check DNS blacklists `GET /v1/tools/blacklist-monitor` checks a domain's mail servers, or one IPv4 address, against DNS blacklists. With `domain`, up to 5 MX hosts (or the domain itself when it has no MX) are resolved to IPv4 addresses and each one is checked. `GET /v1/tools/blacklist-monitor` **Query parameters** | Field | Type | Description | | --- | --- | --- | | `domain` | string | A domain, or an address whose domain is checked. Send `domain` or `ip`. | | `ip` | string | A public IPv4 address to check instead of a domain. | cURL: ```bash curl "https://api.rocketverifier.com/v1/tools/blacklist-monitor?domain=northwind.io" ``` Response 200: ```json { "domain": "northwind.io", "ip": null, "listed": false, "lists_checked": ["zen.spamhaus.org", "bl.spamcop.net"], "details": [ { "list": "zen.spamhaus.org", "zone": "zen.spamhaus.org", "type": "ip", "listed": false, "listed_ips": [] }, { "list": "bl.spamcop.net", "zone": "bl.spamcop.net", "type": "ip", "listed": false, "listed_ips": [] } ], "checked_ips": ["142.250.153.26", "142.250.153.27"], "listings": [], "not_checked": [], "error": null } ``` Read `listed` for the answer and `listings` for each IP and list pair that matched. A list that refused the query or did not answer appears in `not_checked`, never as a listing, so a quiet list cannot produce a false alarm. | Field | Type | Description | | --- | --- | --- | | `domain` | string or null | The checked domain. Null when an `ip` was checked. | | `ip` | string or null | The checked IPv4 address. Null when a domain was checked. | | `listed` | boolean | True when any checked IP is listed. | | `lists_checked` | array of strings | The DNS blacklists queried, such as `zen.spamhaus.org` and `bl.spamcop.net`. | | `checked_ips` | array of strings | The mail server IPv4 addresses that were checked. | | `listings` | array of objects | Every listing found. | | `listings.ip` | string | | | `listings.blacklist` | string | | | `not_checked` | array of objects | IP and list pairs where the list refused the query or did not answer. | | `not_checked.ip` | string | | | `not_checked.blacklist` | string | | | `details` | array of objects | One row per list. | | `details.list` | string | | | `details.zone` | string | | | `details.type` | enum | one of `ip` | | `details.listed` | boolean | | | `details.listed_ips` | array of strings | | | `details.not_checked_ips` | array of strings | Present only when the list did not answer for some IPs. | | `error` | string or null | Set when the domain's IPs could not be resolved. | ## Run a free test lookup `POST /v1/tools/verify-free` runs syntax, MX and disposable checks on one address, without a live SMTP check. It returns `undeliverable` for disposable addresses and domains with no MX, and `unknown` otherwise, because only an SMTP check can confirm a mailbox. `POST /v1/tools/verify-free` cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/tools/verify-free \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "maya@northwind.io"}' ``` Response 200: ```json { "email": "maya@northwind.io", "status": "unknown", "score": 40, "is_disposable": false, "mx_found": true } ``` The response also carries a `note` reminding you that this is a lookup, not a mailbox check. - **Limit:** 2 lookups per IP address per day, with or without a key. The third returns `429 daily_limit_reached`. - **Captcha:** calls without a valid API key must carry a Cloudflare Turnstile `turnstile_token`, as the website's free tool does. A valid key skips the captcha. For real verification at scale, use [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify) or the [sandbox](https://docs.rocketverifier.com/sandbox) for free tests. **Body** | Field | Type | Description | | --- | --- | --- | | `email` | string | The address to look up. required | | `turnstile_token` | string or null | Cloudflare Turnstile token. Required without a valid API key. | ## Read your verification history for an address `GET /v1/tools/activity/{email}` reports how often your account has verified an address and how consistent the results were. It reads your last 50 verifications of the address over the past 90 days, and only your own: organization keys see the organization's history, and no account ever sees another's. It needs a valid API key or OAuth token, no scope and no balance. `GET /v1/tools/activity/{email}` cURL: ```bash curl https://api.rocketverifier.com/v1/tools/activity/maya@northwind.io \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Response 200: ```json { "email": "maya@northwind.io", "verification_count": 4, "activity_score": 40, "stability_score": 100, "last_seen_at": 1762853537, "classifications": { "valid": 4 } } ``` A low `stability_score` means the address has changed answers over time, for example a mailbox that filled up or a domain that turned catch-all. The same scores appear in the `activity` object of every [verify response](https://docs.rocketverifier.com/api/verify#response). | Field | Type | Description | | --- | --- | --- | | `email` | string | The address, trimmed and lowercased. | | `verification_count` | integer | Your verifications of this address in the last 90 days (up to 50). | | `activity_score` | integer | 10 points per verification, capped at 100. 0 to 100 | | `stability_score` | integer | Share of those verifications that returned the most common classification. 100 with one or no verification. 0 to 100 | | `last_seen_at` | integer or null | Unix time of your latest verification of this address. | | `classifications` | object | Count per classification. | ## Errors | Status | `error.code` | When it happens | | --- | --- | --- | | 400 | `missing_input` | The disposable check got neither `email` nor `domain`. | | 400 | `invalid_domain` | The blacklist check got something that is not a domain. | | 400 | `invalid_ip` | The blacklist check got an IP that is not a public IPv4 address. | | 400 | `invalid_email` | The free test lookup got an address with invalid syntax. | | 401 | `unauthorized` | Activity history was called without a valid key. | | 403 | `captcha_failed` | The free test lookup was called without a valid key or Turnstile token. | | 422 | `validation_error` | A required parameter such as `domain` is missing. | | 429 | `rate_limited` | More than 5 anonymous requests per minute from this IP, or your account's limit. | | 429 | `daily_limit_reached` | The free test lookup's 2 lookups per IP per day are used. | | 503 | `service_unavailable` | The limiter is briefly unreachable. Retry shortly. | Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors). ## Frequently asked questions ### Do the lookup tools cost credits? No. MX lookup, disposable check, domain authentication, blacklist check, the free test lookup and activity history are all free. ### Do I need an API key? Only for activity history. The other tools work without a key at 5 requests per minute per IP address. Send your key to get your account's rate limit instead. ### Do these tools verify the mailbox? No. They read DNS and blocklists only. To confirm that a mailbox exists, use POST /v1/verify, which runs a live SMTP check. ### Which blacklists does the blacklist check query? Every list in lists_checked, such as zen.spamhaus.org and bl.spamcop.net. Lists that refuse or ignore the query are reported in not_checked and never counted as listings. --- # Check your credit balance Source: https://docs.rocketverifier.com/api/credits Endpoint: `GET https://api.rocketverifier.com/v1/credits` (OAuth scope `credits:read`) > GET /v1/credits returns the credits available to your key right now, plus the credits charged for verifications today and this month in UTC. It needs the credits:read scope, works at a zero balance and costs nothing. Organization keys on a pooled organization see the pooled balance. cURL: ```bash curl https://api.rocketverifier.com/v1/credits \ -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); const { credits, usedToday, usedThisMonth } = await rv.getCredits(); if (credits < 1000) { // top up before the next import } ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) balance = rv.get_credits() if balance.credits < 1000: pass # top up before the next import print(balance.used_today, balance.used_this_month) ``` Response 200: ```json { "credits": 10000, "used_today": 150, "used_this_month": 2500 } ``` Check the balance before a large import, or show it in your own app. The call is free, needs only the `credits:read` scope and answers even at a zero balance. ## Response | Field | Type | Description | | --- | --- | --- | | `credits` | integer | Credits available to this credential now. | | `used_today` | integer | Credits charged for verifications since 00:00 UTC, before refunds. | | `used_this_month` | integer | Credits charged for verifications since the 1st of the month (UTC), before refunds. | ## What the numbers mean `credits` is what the next charge can draw on. `used_today` and `used_this_month` are what verifications cost in the current UTC day and month. - **`credits`:** the balance available to this credential now, the same number the auth check uses before every charge. - **Usage counts charges, before refunds.** A bulk job is charged in full when it starts, and its unknown results are refunded when it completes. The refund raises `credits` but leaves `used_today` and `used_this_month` as they were. - **Usage covers verifications:** single verifications, bulk jobs and email finder checks. List health monitor runs are not included. - **Usage resets** at 00:00 UTC each day and on the 1st of each month. Credits never expire. Buy more in the [dashboard](https://app.rocketverifier.com/dashboard/buy-credits). ## Organization credit pooling When an organization turns on credit pooling, its members' charges draw on the shared pool whenever the pool covers the full charge, and on the member's own balance otherwise. | Credential | `credits` returns | | --- | --- | | Personal API key | Your own balance. | | Organization API key, pooling on | The larger of the pool and the organization owner's own balance. | | Organization API key, pooling off | The owner's own balance. | | OAuth token that bills a pooled organization | The larger of the pool and the billed user's own balance. | Organization keys act as the organization's owner, so usage is reported for the owner's account. [Teams](https://docs.rocketverifier.com/teams) explains pooling, roles and organization keys. ## Get alerted before you run out Subscribe a [webhook](https://docs.rocketverifier.com/api/webhooks#creditslow-and-creditsdepleted) to `credits.low`, which fires after a charge leaves 100 credits or fewer, and `credits.depleted`, which fires when the balance reaches zero. At zero, every endpoint that charges refuses the call with `403 insufficient_credits` before doing any work. ## What costs credits | Action | Cost | | --- | --- | | [Single verification](https://docs.rocketverifier.com/api/verify) | 1 credit per result. Unknown results and suppressed addresses are free. | | [Bulk job](https://docs.rocketverifier.com/api/batch) or [file upload](https://docs.rocketverifier.com/api/bulk-upload) | 1 credit per unique address. Unknown results and suppressed addresses are refunded at completion. | | [Email finder](https://docs.rocketverifier.com/api/finder) | 1 credit per candidate check with a definite answer, at most 4 per search. | | [List health monitor](https://docs.rocketverifier.com/api/monitors) run | 1 credit per unique address, unknown results refunded. | | Sandbox keys, list health previews, domain monitors, lookup tools, this endpoint | Free. | Hard bounces on addresses a job marked deliverable come back as credits through the [bounce guarantee](https://docs.rocketverifier.com/integrations/bounce-guarantee). ## Errors | Status | `error.code` | When it happens | | --- | --- | --- | | 401 | `unauthorized`, `api_key_expired` | The key is missing, invalid, revoked or expired. | | 403 | `insufficient_scope` | The credential lacks `credits:read`. | | 403 | `ip_not_allowed` | The key has an IP allowlist that does not include the caller. | | 429 | `rate_limited` | Too many requests. Wait for the `Retry-After` seconds. | Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors). ## Frequently asked questions ### Does checking the balance cost a credit? No. GET /v1/credits is free and works even when the balance is zero. ### Why is used_this_month higher than what I paid for? The usage numbers count credits when they are charged, before refunds. Bulk jobs are charged up front and refund unknown results at completion, so the refund shows in credits but not in the usage numbers. ### Do credits expire? No. Credits stay in your account until you use them. ### How do I get told when credits run low? Subscribe a webhook to credits.low (fires at 100 credits or fewer) and credits.depleted (fires at zero). --- # Get the connected account Source: https://docs.rocketverifier.com/api/account Endpoint: `GET https://api.rocketverifier.com/v1/me` (OAuth scope `account:read`) > GET /v1/me returns the account the current credential acts for, whether it bills a personal or an organization account, the available credits and the scopes. OAuth access tokens also get the connected app and its monthly credit cap, and need the account:read scope. API keys can always call it, and it works at a zero balance. cURL: ```bash curl https://api.rocketverifier.com/v1/me \ -H "Authorization: Bearer $ROCKETVERIFIER_ACCESS_TOKEN" ``` Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier({ accessToken: process.env.ROCKETVERIFIER_ACCESS_TOKEN }); const me = await rv.getMe(); console.log(`Connected as ${me.email}, ${me.credits.toLocaleString()} credits`); ``` Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(access_token=os.environ["ROCKETVERIFIER_ACCESS_TOKEN"]) me = rv.get_me() print(f"Connected as {me.email}, {me.credits:,} credits") ``` Response 200: ```json { "email": "jane@acme.com", "name": "Jane Doe", "account_type": "organization", "organization": { "id": "org_8f2a", "name": "Acme Inc" }, "credits": 12400, "auth_type": "oauth", "scopes": ["verify:single", "verify:bulk", "jobs:read", "account:read"], "app": { "client_id": "rvapp_3kq9x2", "name": "Pengo", "monthly_credit_limit": 5000, "credits_used_this_month": 320 } } ``` Apps built on [RocketVerifier Connect](https://docs.rocketverifier.com/oauth/scopes) use this endpoint to show "Connected as jane@acme.com, 12,400 credits" right after the user approves them. With an API key, it is a quick way to check which account and scopes a key carries. ## Request Send the credential in the `Authorization` header. There are no parameters. - **OAuth access tokens** (`rv_at_`) need the `account:read` scope. Without it, the call returns `403 insufficient_scope`. - **API keys** can always call it, whatever their scopes. - **Balance:** works at a zero balance and costs nothing. ## Response | Field | Type | Description | | --- | --- | --- | | `email` | string or null | Email of the user the credential acts for (the owner, for organization keys). | | `name` | string or null | The user's name. Set for OAuth tokens. | | `account_type` | enum | `organization` for organization API keys and for OAuth tokens that bill an organization. required; one of `personal`, `organization` | | `organization` | object or null | Set when the credential bills an organization. | | `organization.id` | string | | | `organization.name` | string or null | Set for OAuth tokens. | | `credits` | integer | Credits available to this credential now. required | | `auth_type` | enum | required; one of `api_key`, `oauth` | | `scopes` | array of strings | The scopes this credential carries. required | | `app` | object or null | The OAuth app the token was issued to. Null for API keys. | | `app.client_id` | string | | | `app.name` | string | | | `app.monthly_credit_limit` | integer or null | Monthly credit cap the user set for this app. Null when uncapped. | | `app.credits_used_this_month` | integer | Credits this app used this month. | ## Read the response by credential The same fields describe four kinds of credential. | Credential | `auth_type` | `account_type` | `organization` | `app` | | --- | --- | --- | --- | --- | | Personal API key | `api_key` | `personal` | `null` | `null` | | Organization API key | `api_key` | `organization` | `{ "id": ... }` | `null` | | OAuth token for a personal account | `oauth` | `personal` | `null` | The connected app | | OAuth token that bills an organization | `oauth` | `organization` | `{ "id", "name" }` | The connected app | - **`email`** is the user the credential acts for. Organization keys act as the organization's owner. - **`credits`** is the balance available to this credential, the same number as [`GET /v1/credits`](https://docs.rocketverifier.com/api/credits). On an organization with credit pooling, it is the larger of the pool and the billed user's own balance. - **`scopes`** lists what the credential can call. Check it before you show features that need a scope the user did not approve. - **`app.monthly_credit_limit`** is the monthly cap the user set for your app, and `app.credits_used_this_month` is what your app used against it. A charge past the cap returns `402 api_key_spend_cap_reached`. ## Errors | Status | `error.code` | When it happens | | --- | --- | --- | | 401 | `unauthorized` | No credential, or an invalid or revoked API key. | | 401 | `api_key_expired` | The API key passed its expiry date. | | 401 | `invalid_token` | The OAuth access token expired or was revoked. Refresh it and retry once. | | 403 | `insufficient_scope` | The OAuth token lacks `account:read`. | | 403 | `ip_not_allowed` | The key or organization has an IP allowlist that does not include the caller. | | 403 | `account_suspended` | The account is suspended. | | 429 | `rate_limited` | Too many requests. Wait for the `Retry-After` seconds. | Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors). The [authentication guide](https://docs.rocketverifier.com/authentication) covers keys and tokens in depth. ## Frequently asked questions ### Does an API key need the account:read scope? No. API keys can always call GET /v1/me. Only OAuth access tokens need account:read. ### What is the difference between /v1/me and /v1/credits? Both return the same available balance. /v1/me adds who the credential acts for and its scopes, and /v1/credits adds today's and this month's usage. ### Which email does an organization API key return? The email of the organization's owner, because organization keys act and are billed as the owner. account_type is organization and organization.id names the organization. --- # 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. --- # Node.js SDK Source: https://docs.rocketverifier.com/sdks/nodejs > Install @rocketverifier/sdk, create a client with your API key and call rv.verify(email). The SDK covers every public endpoint, converts yes and no flags to booleans, retries rate limits with a stable Idempotency-Key and ships full TypeScript types. `@rocketverifier/sdk` is the official Node.js and TypeScript library for the RocketVerifier API. It wraps every endpoint you need in production: real-time verification, bulk jobs from a list or a file, progress and downloads, webhooks, monitors, credits and RocketVerifier Connect OAuth. ## Install the SDK Install from npm. The package has no runtime dependencies and uses the built-in `fetch`, `FormData` and `node:crypto`. Terminal: ```bash npm install @rocketverifier/sdk ``` Both ES module and CommonJS builds are included, with type definitions for each. Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; // or: const { RocketVerifier } = require("@rocketverifier/sdk"); ``` ## Create a client Pass your API key as the first argument, or pass one options object. Read the key from `ROCKETVERIFIER_API_KEY` so it never lands in source control. Node.js: ```js import RocketVerifier from "@rocketverifier/sdk"; const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY); // With options const rv2 = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY, { timeout: 15000, maxRetries: 5, }); // One options object const rv3 = new RocketVerifier({ apiKey: process.env.ROCKETVERIFIER_API_KEY, baseUrl: "https://api.rocketverifier.com" }); ``` The constructor throws an `AuthenticationError` when neither an API key nor an access token is given. Live keys start with `rv_live_`; sandbox keys start with `rv_test_` and accept only [sandbox addresses](https://docs.rocketverifier.com/sandbox). - `apiKey` (string): Your API key. Pass this or `accessToken`. See [authentication](https://docs.rocketverifier.com/authentication). - `accessToken` (string): An OAuth access token (`rv_at_...`) from RocketVerifier Connect. Calls run on the connected user's account and credits. - `refreshToken` (string): An OAuth refresh token (`rv_rt_...`). With `oauth`, the client refreshes the access token automatically on a 401 `invalid_token`. - `oauth` (OAuth | OAuthClientOptions): The OAuth client used for automatic refresh. - `onTokenRefresh` ((tokens) => void | Promise): Called with the new token set after an automatic refresh. Persist the new refresh token here. - `baseUrl` (string, default https://api.rocketverifier.com): API base URL. - `timeout` (number, default 30000): Request timeout in milliseconds, covering the full response body. A value of `0` falls back to the default. - `maxRetries` (number, default 3): Retries after the first attempt, on 429 responses and network errors. Set `0` to turn retries off. - `headers` (Record): Extra headers sent with every request. They are applied last, so they can override the defaults. ## Verify an email `rv.verify(email, idempotencyKey?)` checks one address with [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify) and resolves to a typed `VerificationResult`. Branch on `status` and read `subStatus` for the reason. Node.js: ```js const result = await rv.verify("deliverable@sandbox.rocketverifier.com"); switch (result.status) { case "deliverable": break; // send case "risky": console.log("Review:", result.subStatus, result.catchAllVerdict); break; case "undeliverable": console.log("Remove. Suggestion:", result.didYouMean); break; case "unknown": break; // free: check again later } ``` The SDK rejects input without an `@` before sending a request (`ValidationError`). Pass your own `idempotencyKey` when you retry a call yourself; otherwise a random key is generated per call. The [reading results guide](https://docs.rocketverifier.com/results) explains every status and `sub_status`. ### Result fields The SDK maps the snake_case API response to camelCase fields. | SDK field | API field | Type | | --- | --- | --- | | `email` | `email` | `string` | | `status` | `status` | `"deliverable" \| "undeliverable" \| "risky" \| "unknown"` | | `subStatus` | `sub_status` | `SubStatus`, `"none"` when not specific | | `score` | `score` | `number`, 0 to 100 | | `reason` | `reason` | `string` | | `catchAllVerdict` | `catch_all_verdict` | `"send_safe" \| "send_with_caution" \| "avoid" \| null` | | `didYouMean` | `did_you_mean` | `string \| null` | | `verifiedAt` | `verified_at` | ISO 8601 `string \| null` | | `provider` | `provider` | `string \| null` | | `domain.name` | `domain.name` | `string` | | `domain.acceptAll` | `domain.acceptAll` | `boolean \| null` | | `domain.disposable` | `domain.disposable` | `boolean` | | `domain.free` | `domain.free` | `boolean` | | `domain.acceptAllConfidence` | `domain.acceptAllConfidence` | `number \| null` | | `domain.acceptAllVerdict` | `domain.acceptAllVerdict` | `string \| null` | | `account.role` | `account.role` | `boolean` | | `account.disabled` | `account.disabled` | `boolean \| null` | | `account.fullMailbox` | `account.fullMailbox` | `boolean \| null` | | `dns.type`, `dns.record` | `dns.type`, `dns.record` | `string`, `string \| null` | | `authenticationScore` | `authentication_score` | `number` | | `deliverabilityTier` | `deliverability_tier` | `string` | | `toxic`, `abuse` | `toxic`, `abuse` | `"yes" \| "no" \| "unknown"` | | `spamTrap` | `spam_trap` | `boolean` | | `activity` | `activity` | `{ verificationCount, activityScore, stabilityScore } \| null` | | `evidence` | `evidence` | `Record \| null` | ### Yes and no flags are booleans The API sends flags as the strings `"yes"`, `"no"` and `"unknown"`. The SDK converts them so you can test them directly. - `domain.disposable`, `domain.free`, `account.role` and `spamTrap` become `true` for `"yes"` and `false` otherwise. - `domain.acceptAll`, `account.disabled` and `account.fullMailbox` become `true`, `false` or `null` when the server reports `"unknown"`. - `toxic` and `abuse` keep the original string. Node.js: ```js if (result.domain.disposable || result.account?.role) { // flag the signup } ``` ## Verify a list in bulk `rv.batch` runs bulk jobs of up to 100,000 unique addresses. Create a job, wait for it with a progress callback, then read or download the results. The [batch API reference](https://docs.rocketverifier.com/api/batch) covers the endpoints. Node.js: ```js const job = await rv.batch.create({ name: "October signups", emails: ["deliverable@sandbox.rocketverifier.com", "undeliverable@sandbox.rocketverifier.com"], }); const done = await rv.batch.wait(job.id, { pollInterval: 3000, onProgress: (j) => console.log(`${j.processedEmails}/${j.totalEmails} (${j.progressPercent}%)`), }); const rows = await rv.batch.download(done.id, { parse: true, filter: "send_safe" }); ``` ### Create a job `batch.create({ emails, name?, idempotencyKey? })` resolves to `{ id, jobId, totalEmails, estimatedTimeSeconds, creditsToUse, creditsRemaining }`. The API counts unique addresses, so the SDK throws a `ValidationError` only when the de-duplicated list is larger than 100,000 (`MAX_BULK_EMAILS`). To get a callback when the job finishes, register a [webhook](#manage-webhook-endpoints) for `job.completed`. ### Wait for a job `batch.wait(jobId, options?)` polls the job until it is `completed`, `failed` or `cancelled`, and resolves to the final `BatchJob`. It also returns when a previewed upload reaches `awaiting_confirmation`. | Option | Default | What it does | | --- | --- | --- | | `pollInterval` | `5000` | Milliseconds between status checks. | | `timeout` | `300000` | Maximum wait in milliseconds. Past it, the call throws a `RocketVerifierError` with code `timeout`. | | `onProgress` | none | Called with every `BatchJob` snapshot. | ### Track progress `batch.progress(jobId)` reads the cheap progress endpoint and resolves to a `JobProgress`: `status`, `total`, `processed`, `remaining`, `percent`, `counts` (`valid`, `invalid`, `risky`, `catchAll`, `disposable`, `unknown`), `countsByStatus` (`deliverable`, `undeliverable`, `risky`, `unknown`), `ratePerMinute`, `etaSeconds` and timestamps. Use it for dashboards and progress bars. ### Read results Results come back one page at a time, or through an async iterator that fetches pages as you go. Node.js: ```js const page = await rv.batch.results(jobId, { page: 1, limit: 500, classification: "valid" }); console.log(page.total, page.hasMore); for await (const r of rv.batch.iterateResults(jobId)) { console.log(r.email, r.classification, r.subStatus, r.confidenceScore); } const all = await rv.batch.allResults(jobId); ``` | Method | Returns | Notes | | --- | --- | --- | | `results(jobId, { page, limit, classification })` | `JobResultsPage` | `limit` defaults to 100, up to 1000. | | `iterateResults(jobId, { limit, classification, startPage })` | `AsyncGenerator` | Pages of 1000 by default. | | `allResults(jobId, { limit, classification })` | `JobResult[]` | Every row in one array. | Each `JobResult` has `email`, `classification`, `isValid`, `isDisposable`, `isCatchAll`, `confidenceScore`, `subStatus` and `verifiedAt`. ### Download results `batch.download(jobId, options?)` fetches the full results file of a completed job. The return type follows the options you pass. Node.js: ```js const csv = await rv.batch.download(jobId); // CSV text const rows = await rv.batch.download(jobId, { parse: true }); // typed rows const json = await rv.batch.download(jobId, { format: "json" }); // { job_id, results } const safe = await rv.batch.download(jobId, { filter: "send_safe", parse: true }); const joined = await rv.batch.download(jobId, { includeOriginal: true }); ``` - `filter` keeps only `deliverable`, `undeliverable`, `risky`, `unknown` or `send_safe` rows. `send_safe` is deliverable plus high-scoring catch-all addresses. - `includeOriginal` joins upload jobs with your file's own columns, followed by `rv_status`, `rv_sub_status`, `rv_score` and the other `rv_` columns. - With `parse: true`, `is_valid`, `is_disposable`, `is_catch_all` and `is_role_based` become booleans and `confidence_score` becomes a number. The exported `parseDownloadCsv(text)` does the same for CSV you already have. ### Get, list and cancel jobs | Method | Returns | | --- | --- | | `batch.get(jobId)` | `BatchJob` with counts, `progressPercent` and timestamps. | | `batch.list(limit = 10, page = 1)` | `BatchJob[]`, newest first. | | `batch.listPage({ page, limit, status })` | `{ jobs, total, page, limit, hasMore }`. `limit` defaults to 20, up to 100. | | `batch.delete(jobId)`, `batch.cancel(jobId)` | `{ success, jobId, refundedCredits, message }`. Unprocessed addresses are refunded. | ## Upload a file `batch.upload(options)` creates a job from a CSV, TSV, TXT or XLSX file of up to 50 MB, or from a public HTTPS URL. Pass exactly one of `file` or `sourceUrl`. See [bulk upload](https://docs.rocketverifier.com/api/bulk-upload) for limits and column detection. Node.js: ```js import fs from "node:fs"; const upload = await rv.batch.upload({ file: fs.createReadStream("contacts.csv"), filename: "contacts.csv", emailColumn: "Work Email", preview: true, }); console.log(upload.jobId, upload.status); // "ingesting" ``` | Option | Type | What it does | | --- | --- | --- | | `file` | `Buffer`, `Uint8Array`, `ArrayBuffer`, `Blob`, `File` or a stream | The file content. Streams are read into memory before sending. | | `filename` | `string` | Name with extension. Required unless `file` is a `File` with a name. | | `contentType` | `string` | MIME type. Defaults from the extension. | | `sourceUrl` | `string` | A public HTTPS URL the API fetches instead. | | `name` | `string` | Job name. | | `emailColumn` | `string \| number` | Header name or 0-based index of the email column. | | `columnMapping` | `Record` | For example `{ email: "Work Email" }`. Overrides `emailColumn`. | | `preview` | `boolean` | Stop in `awaiting_confirmation` with a free list health preview. | | `callbackUrl` | `string` | HTTPS URL that receives a signed POST when the job finishes. | | `idempotencyKey` | `string` | Makes your own retries safe. | The result is `{ id, jobId, status, preview, statusUrl, progressUrl, callbackSecret? }`. `callbackSecret` is returned once, only when you set `callbackUrl`. ### Preview and confirm an upload With `preview: true`, the job waits in `awaiting_confirmation` with a free estimate of the list's health. Read it with `batch.preview`, then charge and start the job with `batch.confirm`. Node.js: ```js let res = await rv.batch.preview(upload.jobId); while (res.pending) { await new Promise((r) => setTimeout(r, 2000)); res = await rv.batch.preview(upload.jobId); } console.log(res.preview.estimatedBounceRate, res.preview.creditsNeeded); const confirmed = await rv.batch.confirm(upload.jobId); console.log(confirmed.creditsCharged, confirmed.creditsRemaining); ``` - `batch.preview(jobId, { refresh })` resolves to `{ jobId, status, preview, pending }`. `pending` is `true` while the file is ingesting or the preview is being computed. Preview keys are camelCase, for example `estimatedBounceRate`, `creditsNeeded`, `freeChecks` and `smtpSample`. - `batch.confirm(jobId, idempotencyKey?)` resolves to `{ jobId, status, creditsCharged, creditsRemaining }`. A job is never charged twice, so it is safe to retry. ## Check a domain `rv.domain.check(domain)` combines the MX lookup and disposable check tools into one call and resolves to `{ domain, mxRecords, provider, disposable, hasValidMx }`. Node.js: ```js const info = await rv.domain.check("northwind.io"); console.log(info.hasValidMx, info.mxRecords[0]?.host); ``` ## Read credits and account `rv.getCredits()` resolves to `{ credits, usedToday, usedThisMonth }`. `rv.getMe()` returns the account behind the credential with [`GET /v1/me`](https://docs.rocketverifier.com/api/account): `email`, `name`, `accountType`, `organization`, `credits`, `authType`, `scopes` and `app` (the OAuth app, or `null` for API keys). Node.js: ```js const { credits } = await rv.getCredits(); const me = await rv.getMe(); console.log(`Connected as ${me.email}, ${credits} credits`); ``` ## Manage monitors `rv.monitors` schedules list health re-verification (`list_health`) and SPF, DKIM and DMARC checks (`domain_auth`). Monitors need the `monitors:read` and `monitors:write` scopes. See the [monitors API](https://docs.rocketverifier.com/api/monitors). Node.js: ```js const monitor = await rv.monitors.create({ name: "Newsletter list", type: "list_health", emails: ["maya@northwind.io", "deliverable@sandbox.rocketverifier.com"], frequency: "weekly", alertThreshold: 5, }); const runs = await rv.monitors.runs(monitor.id, 1, 20); ``` | Method | What it does | | --- | --- | | `create({ name, type, frequency, domain, emails, alertThreshold, idempotencyKey })` | `frequency` defaults to `weekly`, `alertThreshold` to `5`. `domain_auth` needs `domain`; `list_health` needs `emails` (up to 5,000). | | `list()`, `get(id)` | Return `Monitor` objects. | | `update(id, { name, frequency, isActive, alertThreshold, domain, emails })` | Changes only the fields you pass. | | `delete(id)` | Removes the monitor. | | `runs(id, page = 1, limit = 20)` | `{ runs, total, page, limit, hasMore }`, most recent first. | | `runNow(id, idempotencyKey?)` | Runs it immediately. `list_health` runs cost 1 credit per address. | ## Manage webhook endpoints `rv.webhooks` registers HTTPS endpoints that receive signed events such as `job.completed`. It needs the `webhooks:manage` scope. The [webhooks API](https://docs.rocketverifier.com/api/webhooks) lists every event and payload. Node.js: ```js const hook = await rv.webhooks.create({ url: "https://northwind.io/hooks/rocketverifier", events: ["job.completed", "job.failed", "credits.low"], }); // Store hook.secret now: it is shown only once. ``` | Method | Returns | | --- | --- | | `listEvents()` | `{ name, description }[]` for every event you can subscribe to. | | `list()`, `get(id)` | `Webhook` with `isActive`, `successCount`, `failureCount` and delivery timestamps. | | `create({ url, name, events, idempotencyKey })` | `Webhook` plus `secret`, `signatureHeader` and `verificationInstructions`. Events default to `job.completed` and `job.failed`. | | `update(id, { name, url, events, isActive })` | The updated `Webhook`. | | `delete(id)` | `{ success, message }`. | | `test(id)` | `{ success, message, statusCode, responseTimeMs }` after a test delivery. | | `logs(id, { page, limit, status })` | Delivery attempts, newest first. `limit` defaults to 50, up to 100. | | `rotateSecret(id)` | `{ success, message, secret }` with the new secret. | ## Verify webhook signatures Every delivery carries `X-RocketVerifier-Signature: t=,v1=`, an HMAC-SHA256 of the timestamp and the raw body. `constructWebhookEvent` checks the signature and the timestamp, then returns the typed event. Node.js: ```js import express from "express"; import { constructWebhookEvent, WebhookSignatureError } from "@rocketverifier/sdk"; const app = express(); app.post("/hooks/rocketverifier", express.raw({ type: "application/json" }), (req, res) => { let event; try { event = constructWebhookEvent( req.body, // raw Buffer, not parsed JSON req.headers["x-rocketverifier-signature"], process.env.ROCKETVERIFIER_WEBHOOK_SECRET ); } catch (err) { if (err instanceof WebhookSignatureError) return res.status(400).send(err.reason); throw err; } if (event.event === "job.completed") { console.log("Job done:", event.data.job_id, event.data.valid_count); } res.sendStatus(200); }); ``` - `verifyWebhookSignature(rawBody, header, secret, { toleranceSec, now })` returns `true` or `false`. - `constructWebhookEvent(rawBody, header, secret, options)` returns the parsed event and throws a `WebhookSignatureError` whose `reason` is `missing_secret`, `invalid_body`, `missing_header`, `malformed_header`, `timestamp_out_of_tolerance`, `signature_mismatch` or `invalid_json`. - `toleranceSec` defaults to 300 seconds. During a secret rotation the header carries more than one `v1` value, and any match passes. - Event payloads keep the API's snake_case keys. `WEBHOOK_SIGNATURE_HEADER` and `WEBHOOK_EVENT_ID_HEADER` export the header names. ## Act for a user with OAuth The `OAuth` class runs the RocketVerifier Connect authorization code flow with PKCE, so your app can verify on another user's account and credits. The [OAuth guide](https://docs.rocketverifier.com/oauth) covers app registration; the [OAuth quickstart](https://docs.rocketverifier.com/oauth/quickstart) walks through a full app. Node.js: ```js import RocketVerifier, { OAuth } from "@rocketverifier/sdk"; const oauth = new OAuth({ clientId: process.env.RV_CLIENT_ID, clientSecret: process.env.RV_CLIENT_SECRET, redirectUri: "https://northwind.io/rocketverifier/callback", }); // 1. Send the user to the consent screen const { url, state, codeVerifier } = oauth.getAuthorizeUrl({ scopes: ["verify:bulk", "account:read"] }); // store state and codeVerifier in the session, then redirect to url // 2. On the callback, after checking state const tokens = await oauth.exchangeCode({ code: req.query.code, codeVerifier }); // 3. Call the API for that user, with automatic refresh const userRv = new RocketVerifier({ accessToken: tokens.accessToken, refreshToken: tokens.refreshToken, oauth, onTokenRefresh: async (t) => saveTokens(userId, t), }); ``` | Member | What it does | | --- | --- | | `new OAuth({ clientId, clientSecret, redirectUri, issuer, tokenEndpointAuthMethod })` | Omit `clientSecret` for public clients. `issuer` defaults to `https://app.rocketverifier.com`; `tokenEndpointAuthMethod` to `client_secret_basic`. | | `getAuthorizeUrl({ scopes, redirectUri, state, codeVerifier, resource, prompt })` | Returns `{ url, state, codeVerifier }`. `state` and the PKCE verifier are generated when omitted. | | `exchangeCode({ code, codeVerifier, redirectUri })` | Returns an `OAuthTokenSet`. Codes are single use and expire after 60 seconds. | | `refresh(refreshToken)` | Returns a new token set. The refresh token rotates on every use. | | `revoke(token, tokenTypeHint?)` | Revokes a token. Revoking a refresh token ends the connection. | | `introspect(token)` | Returns `{ active, scope, clientId, tokenType, exp, ... }`. | An `OAuthTokenSet` holds `accessToken`, `refreshToken`, `tokenType`, `expiresIn` (seconds), `expiresAt` (Unix milliseconds) and `scopes`. ### How token refresh works When the API answers 401 `invalid_token` and the client has both `refreshToken` and `oauth`, it refreshes once, retries the call and passes the new tokens to `onTokenRefresh`. Concurrent calls share a single refresh, because refresh tokens are single use. Without refresh configured, the call throws an `InvalidTokenError`. If the refresh token itself is rejected, `oauth.refresh` throws an `OAuthError` with `error === "invalid_grant"`: send the user through Connect again. Use `rv.setTokens({ accessToken, refreshToken })` to swap in tokens you refreshed elsewhere. `OAUTH_SCOPES`, `generatePkcePair()` and `pkceChallenge()` are exported for custom flows. ## Handle errors Every error extends `RocketVerifierError`, which carries `message`, `code`, `statusCode` and `details`. Catch the subclasses you act on and fall back to the base class. | Class | Thrown when | `code` | | --- | --- | --- | | `AuthenticationError` | 401, or no credential passed to the constructor. | `unauthorized` | | `InvalidTokenError` | 401 `invalid_token` for an OAuth token that cannot be refreshed. Extends `AuthenticationError`. | `invalid_token` | | `InsufficientCreditsError` | 402. | `insufficient_credits` | | `RateLimitError` | 429 after all retries. `retryAfter` holds the seconds to wait. | `rate_limit_exceeded` | | `ValidationError` | 400, or input the SDK rejects before sending. | `validation_error` | | `WebhookSignatureError` | `constructWebhookEvent` cannot trust a delivery. `reason` says why. | `webhook_signature_invalid` | | `OAuthError` | The token, revoke or introspect endpoint returns an error. `error` holds the OAuth code. | the OAuth error | | `RocketVerifierError` | Every other status, including 403, 404 and 422, plus timeouts and network failures. | the API's `error.code`, `timeout` or `network_error` | A zero balance is refused with a 403 before any check runs, so test `err.code === "insufficient_credits"` to catch both the 402 and the 403 case. Node.js: ```js import { RocketVerifierError, RateLimitError } from "@rocketverifier/sdk"; try { await rv.verify("maya@northwind.io"); } catch (err) { if (err instanceof RateLimitError) { console.log(`Slow down for ${err.retryAfter}s`); } else if (err instanceof RocketVerifierError && err.code === "insufficient_credits") { console.log("Top up credits"); } else { throw err; } } ``` The [errors reference](https://docs.rocketverifier.com/errors) lists every API error code. ## Retries and timeouts The client retries only what is safe and useful to retry, and never charges twice for a retried call. - **Rate limits (429):** retried up to `maxRetries` times. Each retry waits for the `Retry-After` seconds, or 60 seconds when the header is missing. See [rate limits](https://docs.rocketverifier.com/rate-limits). - **Network errors:** retried up to `maxRetries` times, waiting 1, 2 and 3 seconds. - **Timeouts:** not retried. The call throws a `RocketVerifierError` with code `timeout` and status 408 once `timeout` milliseconds pass. - **Other errors:** 4xx and 5xx responses are thrown straight away. - **Idempotency:** every POST, PUT and PATCH sends an `Idempotency-Key`, generated per call and reused on every retry of that call. Set `maxRetries: 0` to handle every retry yourself. ## TypeScript types The package is written in TypeScript and exports a type for every request and response. `subStatus` is typed as `SubStatus` with a string fallback, so every value the API returns compiles. TypeScript: ```ts import RocketVerifier, { type VerificationResult, type VerificationStatus, type SubStatus, type BatchJob, type JobProgress, type WebhookEvent, MAX_BULK_EMAILS, SDK_VERSION, } from "@rocketverifier/sdk"; function canSend(r: VerificationResult): boolean { return r.status === "deliverable" || r.catchAllVerdict === "send_safe"; } ``` Other exports include `CatchAllVerdict`, `BatchJobStatus`, `JobResult`, `BatchDownloadRow`, `BulkPreview`, `Monitor`, `Webhook`, `WebhookEventType`, `OAuthTokenSet`, `OAuthScope`, `AccountProfile`, `CreditBalance`, `MAX_UPLOAD_BYTES`, `UPLOAD_EXTENSIONS`, `USER_AGENT`, `parseCsv` and `parseDownloadCsv`. ## Next steps - [Reading results](https://docs.rocketverifier.com/results) Every status and sub_status, what it costs and what to do with it. - [Sandbox and testing](https://docs.rocketverifier.com/sandbox) Fixed results for tests and CI, with no credits spent. - [Webhooks](https://docs.rocketverifier.com/api/webhooks) Events, payloads and delivery retries. - [All SDKs](https://docs.rocketverifier.com/sdks) Compare the Node.js, Python, Go, PHP and Ruby libraries and the CLI. ## Frequently asked questions ### Does the Node.js SDK work with CommonJS and ES modules? Yes. The package ships both builds. Use `import RocketVerifier from "@rocketverifier/sdk"` or `const { RocketVerifier } = require("@rocketverifier/sdk")`. ### Which errors does the SDK retry? Rate limits (429) and network errors, up to `maxRetries` times (3 by default). A 429 waits for the `Retry-After` seconds. Timeouts and 5xx responses are thrown straight away. ### Can a retry charge me twice? No. Every POST and PATCH carries an Idempotency-Key that the SDK reuses across its own retries, so the API returns the original result instead of charging again. ### Why is result.domain.disposable a boolean when the API returns a string? The SDK converts the API's `"yes"`, `"no"` and `"unknown"` strings for you. Flags that can be unknown, such as `domain.acceptAll`, become `true`, `false` or `null`. --- # Python SDK Source: https://docs.rocketverifier.com/sdks/python > Run pip install rocketverifier, create RocketVerifier(api_key) and call rv.verify(email). The package covers every public endpoint with dataclass results, a matching AsyncRocketVerifier on httpx, safe retries with a stable Idempotency-Key and webhook signature helpers. `rocketverifier` is the official Python library for the RocketVerifier API. One install gives you a synchronous client on `requests` and an async client on `httpx`, with the same methods: real-time verification, bulk jobs from a list or a file, progress and downloads, webhooks, monitors, credits and RocketVerifier Connect OAuth. ## Install the SDK Install from PyPI. Add the `async` extra for `AsyncRocketVerifier`. Terminal: ```bash pip install rocketverifier pip install "rocketverifier[async]" # adds httpx for AsyncRocketVerifier ``` `rocketverifier.__version__` holds the installed version, and every request sends it in the `User-Agent` header. ## Create a client Pass your API key as the first argument. Read it from `ROCKETVERIFIER_API_KEY` so it never lands in source control. Use the client as a context manager, or call `close()` when you are done. Python: ```python import os from rocketverifier import RocketVerifier rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) with RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"], timeout=15, max_retries=5) as rv: print(rv.verify("deliverable@sandbox.rocketverifier.com").status) ``` The constructor raises `AuthenticationError` when neither `api_key` nor `access_token` is given. Live keys start with `rv_live_`; sandbox keys start with `rv_test_` and accept only [sandbox addresses](https://docs.rocketverifier.com/sandbox). - `api_key` (str): Your API key. Pass this or `access_token`. See [authentication](https://docs.rocketverifier.com/authentication). - `base_url` (str, default https://api.rocketverifier.com): API base URL. - `timeout` (float, default 30.0): HTTP timeout in seconds. - `max_retries` (int, default 3): Retries after the first attempt, on 429 responses, timeouts and connection errors. Set `0` to turn retries off. - `access_token` (str): Keyword only. An OAuth access token (`rv_at_...`) from RocketVerifier Connect. Calls run on the connected user's account and credits. - `refresh_token` (str): Keyword only. An OAuth refresh token (`rv_rt_...`). With `oauth`, a 401 `invalid_token` triggers one refresh and a retry. - `oauth` (OAuth): Keyword only. The OAuth client used for automatic refresh. - `on_token_refresh` (Callable[[TokenSet], Any]): Keyword only. Called with the new `TokenSet` after an automatic refresh. Persist the new refresh token here. ## Verify an email `rv.verify(email, idempotency_key=None, timeout=None)` checks one address with [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify) and returns a `VerificationResult` dataclass. Branch on `status` and read `sub_status` for the reason. Python: ```python result = rv.verify("deliverable@sandbox.rocketverifier.com") if result.status == "deliverable": pass # send elif result.status == "risky": print("Review:", result.sub_status, result.catch_all_verdict) elif result.status == "undeliverable": print("Remove. Suggestion:", result.did_you_mean) else: pass # unknown: free, check again later ``` - `timeout` is the server side verification timeout in seconds. The SDK accepts 5 to 60 and raises the HTTP timeout to cover it. - Pass your own `idempotency_key` when you retry a call yourself; otherwise a random key is generated per call. - Input without an `@` raises `ValidationError` before any request is sent. The [reading results guide](https://docs.rocketverifier.com/results) explains every status and `sub_status`. ### Result fields `VerificationResult` uses the API's snake_case names. | Field | Type | Notes | | --- | --- | --- | | `email` | `str` | | | `status` | `str` | `deliverable`, `undeliverable`, `risky` or `unknown` | | `sub_status` | `str` | One of `SUB_STATUSES`, `"none"` when not specific | | `score` | `int` | 0 to 100 | | `reason` | `str` | | | `catch_all_verdict` | `str \| None` | `send_safe`, `send_with_caution` or `avoid` for catch-all domains | | `did_you_mean` | `str \| None` | Typo suggestion | | `verified_at` | `str \| None` | ISO 8601 | | `provider` | `str \| None` | For example `google.com` | | `domain` | `DomainInfo` | `name`, `accept_all`, `disposable`, `free`, `accept_all_confidence`, `accept_all_verdict` | | `account` | `AccountInfo \| None` | `role`, `disabled`, `full_mailbox` | | `dns` | `DNSInfo \| None` | `type`, `record` | | `authentication_score` | `int \| None` | SPF, DKIM and DMARC score | | `deliverability_tier` | `str \| None` | | | `toxic`, `abuse` | `str \| None` | `"yes"`, `"no"` or `"unknown"` | | `spam_trap` | `bool \| None` | | | `activity`, `evidence` | `dict \| None` | | | `raw` | `dict` | The full response, for any field not named above | `result.is_deliverable` (alias `is_valid`) is `True` when `status == "deliverable"`. ### Yes and no flags are booleans The API sends flags as the strings `"yes"`, `"no"` and `"unknown"`. The SDK converts them. - `domain.disposable`, `domain.free` and `account.role` are `bool`. - `domain.accept_all`, `account.disabled`, `account.full_mailbox` and `spam_trap` are `True`, `False` or `None` when the server reports `"unknown"`. - `toxic` and `abuse` keep the original string. Python: ```python if result.domain.disposable or (result.account and result.account.role): flag_signup(result.email) ``` ## Verify a list in bulk `rv.batch` runs bulk jobs of up to 100,000 addresses. Create a job, wait for it with a progress callback, then read or download the results. The [batch API reference](https://docs.rocketverifier.com/api/batch) covers the endpoints. Python: ```python job = rv.batch.create( emails=["deliverable@sandbox.rocketverifier.com", "undeliverable@sandbox.rocketverifier.com"], name="October signups", ) print(job.id, job.credits_to_use, job.credits_remaining) done = rv.batch.wait( job.id, poll_interval=3, on_progress=lambda j: print(f"{j.processed_emails}/{j.total_emails} ({j.progress:.0f}%)"), ) rows = rv.batch.download(done.id, parse=True, filter="send_safe") ``` ### Create a job `batch.create(emails, name=None, idempotency_key=None)` returns a `BatchJob` with `id`, `status` (`pending`), `total_emails`, `credits_to_use`, `credits_remaining` and `estimated_time_seconds`. Lists longer than 100,000 entries raise `ValidationError`. To get a callback when the job finishes, register a [webhook](#manage-webhook-endpoints) for `job.completed`. ### Wait for a job `batch.wait(job_id, poll_interval=5.0, timeout=300.0, on_progress=None)` polls until the job is `completed`, `failed` or `cancelled`, and returns the final `BatchJob`. It also returns when a previewed upload reaches `awaiting_confirmation`. Past `timeout` seconds it raises `RocketVerifierError` with code `timeout`. `BatchJob` has `id`, `name`, `status`, `total_emails`, `processed_emails`, `valid_count`, `invalid_count`, `risky_count`, `catch_all_count`, `disposable_count`, `unknown_count`, `progress_percent`, `credits_used`, `download_url` and timestamps, plus the properties `progress`, `is_completed`, `is_failed`, `is_cancelled`, `is_finished` and `is_awaiting_confirmation`. ### Track progress `batch.progress(job_id)` reads the cheap progress endpoint and returns a `JobProgress`: `status`, `total`, `processed`, `remaining`, `percent`, `counts` (`valid`, `invalid`, `risky`, `catch_all`, `disposable`, `unknown`), `counts_by_status` (`deliverable`, `undeliverable`, `risky`, `unknown`), `rate_per_minute`, `eta_seconds` and timestamps. Python: ```python p = rv.batch.progress(job.id) print(f"{p.percent}% done, ETA {p.eta_seconds}s") ``` ### Read results Python: ```python page = rv.batch.results(job.id, page=1, limit=500) print(page.total, page.has_more) valid = [r.email for r in rv.batch.iter_results(job.id) if r.is_valid] ``` - `batch.results(job_id, page=1, limit=100)` returns a `JobResultsPage` (`limit` up to 1000). - `batch.iter_results(job_id, page_size=1000)` yields every `JobResult`, fetching pages as you go. - Each `JobResult` has `email`, `classification`, `is_valid`, `is_disposable`, `is_catch_all`, `is_role_based`, `confidence_score`, `sub_status` and `verified_at`. ### Download results `batch.download(job_id, format="csv", parse=False, filter=None, include_original=False)` fetches the full results file of a completed job. Python: ```python csv_text = rv.batch.download(job.id) rows = rv.batch.download(job.id, parse=True) # list of dicts data = rv.batch.download(job.id, format="json") # {"job_id": ..., "results": [...]} safe = rv.batch.download(job.id, filter="send_safe", parse=True) ``` - `filter` keeps only `deliverable`, `undeliverable`, `risky`, `unknown` or `send_safe` rows. `send_safe` is deliverable plus high-scoring catch-all addresses. - `include_original=True` joins upload jobs with your file's own columns, followed by `rv_status`, `rv_sub_status`, `rv_score` and the other `rv_` columns. - With `parse=True`, the boolean columns become `bool`, `confidence_score` becomes a number and an empty `verified_at` becomes `None`. `parse_results_csv(text)` does the same for CSV you already have. - A job that is still running raises `ValidationError` with `code == "job_not_complete"`. ### Get, list and cancel jobs | Method | Returns | | --- | --- | | `batch.get(job_id)` | `BatchJob` | | `batch.list(limit=10, offset=0, status=None)` | `list[BatchJob]`, newest first | | `batch.list_page(page=1, limit=20, status=None)` | `JobsPage` with `jobs`, `total`, `page`, `limit`, `has_more`. `limit` up to 100. | | `batch.delete(job_id)`, `batch.cancel(job_id)` | `JobCancelResult` with `success`, `job_id`, `refunded_credits`, `message` | ## Upload a file `batch.upload()` creates a job from a CSV, TSV, TXT or XLSX file of up to 50 MB, or from a public HTTPS URL. Pass exactly one of `file` or `source_url`. See [bulk upload](https://docs.rocketverifier.com/api/bulk-upload) for limits and column detection. Python: ```python up = rv.batch.upload("contacts.csv", email_column="Work Email", preview=True) print(up.job_id, up.status) # ..., "ingesting" up2 = rv.batch.upload(source_url="https://northwind.io/exports/leads.csv", name="Leads") ``` | Argument | What it does | | --- | --- | | `file` | A path, `bytes`, or a binary file object. | | `filename` | Name with extension. Defaults to the path or the file object's name. | | `source_url` | Keyword only. A public HTTPS URL the API fetches instead. | | `name` | Job name. | | `email_column` | Header name or 0-based index of the email column. | | `column_mapping` | For example `{"email": "Work Email"}`. Overrides `email_column`. | | `preview` | Stop in `awaiting_confirmation` with a free list health preview. | | `callback_url` | HTTPS URL that receives a signed POST when the job finishes. | | `content_type` | MIME type of the file part. Defaults from the extension. | | `idempotency_key` | Makes your own retries safe. | The result is a `BulkUpload` with `job_id` (also `id`), `status`, `preview`, `status_url`, `progress_url` and `callback_secret`, which is returned once when you set `callback_url`. ### Preview and confirm an upload With `preview=True`, the job waits in `awaiting_confirmation` with a free estimate of the list's health. Read it with `batch.preview`, then charge and start the job with `batch.confirm`. Python: ```python import time res = rv.batch.preview(up.job_id) while res.pending: time.sleep(2) res = rv.batch.preview(up.job_id) print(res.preview.estimated_bounce_rate, res.preview.credits_needed) confirmed = rv.batch.confirm(up.job_id) print(confirmed.credits_charged, confirmed.credits_remaining) ``` - `batch.preview(job_id, refresh=False)` returns a `BulkPreviewResult` with `job_id`, `status`, `preview` and `pending`. `BulkPreview` has `estimated_bounce_rate`, `undeliverable_share`, `risky_share`, `unknown_share`, `credits_needed`, `estimated_credits_after_refunds`, `free_checks`, `smtp_sample` and `confidence`. - `batch.confirm(job_id, idempotency_key=None)` returns a `BulkConfirmResult` with `credits_charged` and `credits_remaining`. A job is never charged twice, so it is safe to retry. ## Check a domain `rv.domain.check(domain)` combines the MX lookup and disposable check tools and returns a `DomainCheckResult` with `domain`, `mx_records` (each with `priority` and `host`), `provider`, `disposable` and `has_valid_mx`. Python: ```python info = rv.domain.check("northwind.io") print(info.has_valid_mx, info.mx_records[0].host if info.mx_records else None) ``` ## Read credits and account `rv.get_credits()` returns `credits`, `used_today` and `used_this_month`. `rv.get_me()` returns the account behind the credential with [`GET /v1/me`](https://docs.rocketverifier.com/api/account): `email`, `name`, `account_type`, `organization`, `credits`, `auth_type`, `scopes` and `app`. Python: ```python me = rv.get_me() print(f"Connected as {me.email}, {rv.get_credits().credits} credits") ``` ## Manage monitors `rv.monitors` schedules list health re-verification (`list_health`) and SPF, DKIM and DMARC checks (`domain_auth`). Monitors need the `monitors:read` and `monitors:write` scopes. See the [monitors API](https://docs.rocketverifier.com/api/monitors). Python: ```python monitor = rv.monitors.create( name="Newsletter list", type="list_health", emails=["maya@northwind.io", "deliverable@sandbox.rocketverifier.com"], ) runs = rv.monitors.runs(monitor.id, page=1, limit=20) ``` | Method | What it does | | --- | --- | | `create(name, type, frequency="weekly", domain=None, emails=None, alert_threshold=5, idempotency_key=None)` | `domain_auth` needs `domain`; `list_health` needs `emails`. | | `list()`, `get(monitor_id)` | Return `Monitor` objects. | | `update(monitor_id, name=, frequency=, is_active=, alert_threshold=, domain=, emails=)` | Changes only the arguments you pass. | | `delete(monitor_id)` | Removes the monitor and its run history. | | `runs(monitor_id, page=1, limit=20)` | `MonitorRunsPage`, most recent first. | | `run_now(monitor_id, idempotency_key=None)` | Runs it immediately and returns the response dict. `list_health` runs cost 1 credit per address. | ## Manage webhook endpoints `rv.webhooks` registers HTTPS endpoints that receive signed events such as `job.completed`. It needs the `webhooks:manage` scope. The [webhooks API](https://docs.rocketverifier.com/api/webhooks) lists every event and payload. Python: ```python hook = rv.webhooks.create( "https://northwind.io/hooks/rocketverifier", events=["job.completed", "job.failed", "credits.low"], ) save_secret(hook.secret) # shown only once ``` | Method | Returns | | --- | --- | | `events()` | `list[WebhookEventType]` with `name` and `description`. | | `list()`, `get(webhook_id)` | `Webhook` with `is_active`, `success_count`, `failure_count` and delivery timestamps. | | `create(url, events=None, name=None)` | `Webhook` with `secret`, `signature_header` and `verification_instructions`. The URL must use HTTPS. Events default to `job.completed` and `job.failed`. | | `update(webhook_id, name=, url=, events=, is_active=)` | The updated `Webhook`. Pass at least one field. | | `delete(webhook_id)` | `{"success": True, "message": ...}` | | `test(webhook_id)` | `WebhookTestResult` with `success`, `message`, `status_code`, `response_time_ms`. | | `logs(webhook_id, page=1, limit=50, status=None)` | `WebhookLogsPage`. `status` is `pending`, `success`, `failed` or `retrying`. | | `rotate_secret(webhook_id)` | `{"success", "message", "secret"}` with the new secret. | ## Verify webhook signatures Every delivery carries `X-RocketVerifier-Signature: t=,v1=`, an HMAC-SHA256 of the timestamp and the raw body. `construct_event` checks the signature and the timestamp, then returns the parsed event. Python: ```python import os from flask import Flask, request from rocketverifier import construct_event, WebhookSignatureError, SIGNATURE_HEADER app = Flask(__name__) @app.post("/hooks/rocketverifier") def rocketverifier_webhook(): try: event = construct_event( request.get_data(), # raw bytes, not parsed JSON request.headers.get(SIGNATURE_HEADER, ""), os.environ["ROCKETVERIFIER_WEBHOOK_SECRET"], ) except WebhookSignatureError as e: return e.code, 400 if event["event"] == "job.completed": print("Job done:", event["data"]["job_id"]) return "", 204 ``` - `verify_webhook_signature(raw_body, header, secret, tolerance=300, now=None)` returns `True` or `False`. - `construct_event(raw_body, header, secret, tolerance=300, now=None)` returns the event dict and raises `WebhookSignatureError` whose `code` is `invalid_signature_header`, `timestamp_outside_tolerance`, `signature_mismatch`, `missing_secret` or `invalid_payload`. - Pass the body as `bytes` or `str` exactly as received. A parsed dict raises `TypeError`. - During a secret rotation the header carries more than one `v1` value, and any match passes. - `generate_signature_header(raw_body, secret)` builds a valid header for testing your endpoint locally. ## Act for a user with OAuth The `OAuth` class runs the RocketVerifier Connect authorization code flow with PKCE, so your app can verify on another user's account and credits. The [OAuth guide](https://docs.rocketverifier.com/oauth) covers app registration; the [OAuth quickstart](https://docs.rocketverifier.com/oauth/quickstart) walks through a full app. Python: ```python import os from rocketverifier import OAuth, RocketVerifier oauth = OAuth( client_id=os.environ["RV_CLIENT_ID"], client_secret=os.environ["RV_CLIENT_SECRET"], redirect_uri="https://northwind.io/rocketverifier/callback", ) # 1. Send the user to the consent screen auth = oauth.get_authorize_url(scopes=["verify:bulk", "account:read"]) # store auth.state and auth.code_verifier in the session, then redirect to auth.url # 2. On the callback, after checking state tokens = oauth.exchange_code(code=code, code_verifier=auth.code_verifier) # 3. Call the API for that user, with automatic refresh user_rv = RocketVerifier( access_token=tokens.access_token, refresh_token=tokens.refresh_token, oauth=oauth, on_token_refresh=lambda t: save_tokens(user_id, t), ) ``` | Member | What it does | | --- | --- | | `OAuth(client_id, client_secret=None, redirect_uri=None, issuer=..., token_endpoint_auth_method="client_secret_basic", timeout=30.0)` | Omit `client_secret` for public clients. `issuer` defaults to `https://app.rocketverifier.com`. | | `get_authorize_url(scopes, redirect_uri=, state=, code_verifier=, resource=, prompt=)` | `AuthorizeUrl` with `url`, `state` and `code_verifier`, generated when omitted. | | `exchange_code(code, code_verifier, redirect_uri=None)` | `TokenSet`. Codes are single use and expire after 60 seconds. | | `refresh(refresh_token)` | A new `TokenSet`. The refresh token rotates on every use. | | `revoke(token, token_type_hint=None)` | Revokes a token. Revoking a refresh token ends the connection. | | `introspect(token)` | The raw introspection dict (`active`, `scope`, ...). | | `aexchange_code`, `arefresh`, `arevoke`, `aintrospect` | Async versions on `httpx`. | A `TokenSet` holds `access_token`, `refresh_token`, `token_type`, `expires_in` (seconds), `expires_at` (Unix seconds) and `scopes`. ### How token refresh works When the API answers 401 `invalid_token` and the client has both `refresh_token` and `oauth`, it refreshes once, retries the call and passes the new tokens to `on_token_refresh`. A lock makes concurrent threads share one refresh, because refresh tokens are single use. Without refresh configured, the call raises `InvalidTokenError`. If the refresh token itself is rejected, `OAuthError` is raised with `error == "invalid_grant"`: send the user through Connect again. Use `rv.set_tokens(access_token, refresh_token=None)` to swap in tokens you refreshed elsewhere. `OAUTH_SCOPES`, `generate_pkce_pair()` and `pkce_challenge()` are exported for custom flows. ## Use the async client `AsyncRocketVerifier` has the same methods as the sync client, as coroutines. Install the `async` extra, then use it as an async context manager or call `await rv.aclose()`. Python: ```python import asyncio, os from rocketverifier import AsyncRocketVerifier async def main(): async with AsyncRocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"]) as rv: emails = ["maya@northwind.io", "deliverable@sandbox.rocketverifier.com"] results = await asyncio.gather(*(rv.verify(e) for e in emails)) for r in results: print(r.email, r.status) job = await rv.batch.create(emails=emails) await rv.batch.wait(job.id) async for row in rv.batch.iter_results(job.id): print(row.email, row.classification) asyncio.run(main()) ``` - The constructor takes the same arguments plus `transport`, an `httpx.AsyncBaseTransport` for proxies or `httpx.MockTransport` in tests. - `on_token_refresh` can be a plain function or a coroutine function. - `AsyncRocketVerifier` is imported lazily, so the sync client works without `httpx` installed. ## Handle errors Every exception extends `RocketVerifierError`, which carries `message`, `code`, `status_code` and `details`. | Exception | Raised when | `code` | | --- | --- | --- | | `AuthenticationError` | 401, or no credential passed to the constructor. | `unauthorized` | | `InvalidTokenError` | 401 `invalid_token` for an OAuth token that cannot be refreshed. Extends `AuthenticationError`. | `invalid_token` | | `InsufficientCreditsError` | 402, or any response with code `insufficient_credits` (including the 403 at zero balance). | `insufficient_credits` | | `RateLimitError` | 429 after all retries. `retry_after` holds the seconds to wait. | `rate_limit_exceeded` | | `ValidationError` | 400 or 422, or input the SDK rejects before sending. | the API's code, such as `validation_error` or `job_not_complete` | | `PermissionDeniedError` | 403, for example a missing scope or an IP allowlist. | the API's code, or `forbidden` | | `NotFoundError` | 404: the job, webhook or monitor does not exist. | the API's code, or `not_found` | | `WebhookSignatureError` | `construct_event` cannot trust a delivery. | see [signatures](#verify-webhook-signatures) | | `OAuthError` | The token, revoke or introspect endpoint returns an error. `error` holds the OAuth code. | the OAuth error | | `RocketVerifierError` | Every other status, timeouts and network failures. | the API's code, `timeout` or `network_error` | Python: ```python from rocketverifier import InsufficientCreditsError, RateLimitError, RocketVerifierError try: rv.verify("maya@northwind.io") except RateLimitError as e: print(f"Slow down for {e.retry_after}s") except InsufficientCreditsError: print("Top up credits") except RocketVerifierError as e: print(e.code, e.status_code, e.message) ``` The [errors reference](https://docs.rocketverifier.com/errors) lists every API error code. ## Retries and timeouts The client retries only what is safe and useful to retry, and never charges twice for a retried call. - **Rate limits (429):** retried up to `max_retries` times. Each retry waits for the `Retry-After` seconds, or 60 seconds when the header is missing. See [rate limits](https://docs.rocketverifier.com/rate-limits). - **Timeouts and connection errors:** retried up to `max_retries` times, waiting 1, 2 and 3 seconds. After the last attempt, a timeout raises `RocketVerifierError` with code `timeout`. - **Other errors:** 4xx and 5xx responses raise straight away. - **Idempotency:** every POST, PUT and PATCH sends an `Idempotency-Key`, generated per call and reused on every retry of that call. Set `max_retries=0` to handle every retry yourself. ## Type hints Every model is a dataclass with full type hints, and the package exports its constants: `SUB_STATUSES`, `CATCH_ALL_VERDICTS`, `JOB_STATUSES`, `SIGNATURE_HEADER`, `EVENT_ID_HEADER` and `OAUTH_SCOPES`. New `sub_status` values arrive as plain strings, so compare against the values you act on and keep a default branch. Python: ```python from rocketverifier import VerificationResult, CATCH_ALL_VERDICTS def can_send(r: VerificationResult) -> bool: return r.status == "deliverable" or r.catch_all_verdict == "send_safe" ``` ## Next steps - [Reading results](https://docs.rocketverifier.com/results) Every status and sub_status, what it costs and what to do with it. - [Sandbox and testing](https://docs.rocketverifier.com/sandbox) Fixed results for tests and CI, with no credits spent. - [Webhooks](https://docs.rocketverifier.com/api/webhooks) Events, payloads and delivery retries. - [All SDKs](https://docs.rocketverifier.com/sdks) Compare the Node.js, Python, Go, PHP and Ruby libraries and the CLI. ## Frequently asked questions ### Is there an async client? Yes. Install `rocketverifier[async]` and use `AsyncRocketVerifier`. It has the same methods as the sync client, built on `httpx.AsyncClient`. ### Which errors does the SDK retry? Rate limits (429), timeouts and connection errors, up to `max_retries` times (3 by default). A 429 waits for the `Retry-After` seconds. Other 4xx and 5xx responses raise straight away. ### Are the yes and no fields booleans in Python? Yes. `result.domain.disposable` and `result.account.role` are `bool`. Fields that can be unknown, such as `domain.accept_all`, are `True`, `False` or `None`. ### How do I read a response field the dataclass does not name? Every `VerificationResult` keeps the full response in `result.raw`, for example `result.raw.get("retry_after")`. --- # Go SDK Source: https://docs.rocketverifier.com/sdks/go > Run go get github.com/rocketverifier/sdk-go, create a client with rocketverifier.New(apiKey) and call rv.Verify(ctx, email, nil). The module uses only the standard library, takes a context on every call, retries safely with a stable Idempotency-Key and returns typed errors you match with errors.Is. `github.com/rocketverifier/sdk-go` is the official Go client for the RocketVerifier API. It covers real-time verification, bulk jobs from a list or a file, progress and downloads, webhooks, monitors, credits and RocketVerifier Connect OAuth, with no dependencies outside the standard library. ## Install the SDK Add the module to your project. The package name is `rocketverifier`. Terminal: ```bash go get github.com/rocketverifier/sdk-go ``` Go: ```go import rocketverifier "github.com/rocketverifier/sdk-go" ``` ## Create a client `rocketverifier.New(apiKey, opts...)` returns a `*Client` that is safe for concurrent use. Read the key from `ROCKETVERIFIER_API_KEY` so it never lands in source control. Go: ```go rv, err := rocketverifier.New( os.Getenv("ROCKETVERIFIER_API_KEY"), rocketverifier.WithTimeout(15*time.Second), rocketverifier.WithMaxRetries(5), ) if err != nil { log.Fatal(err) } ``` `New` returns an error when the key is empty. Live keys start with `rv_live_`; sandbox keys start with `rv_test_` and accept only [sandbox addresses](https://docs.rocketverifier.com/sandbox). See [authentication](https://docs.rocketverifier.com/authentication). | Option | Default | What it does | | --- | --- | --- | | `WithBaseURL(url)` | `https://api.rocketverifier.com` | API base URL. | | `WithTimeout(d)` | `30 * time.Second` | Timeout per attempt. Each retry gets the full timeout again. | | `WithMaxRetries(n)` | `3` | Retries on 429, timeouts and network errors. `0` turns retries off. | | `WithHTTPClient(hc)` | `&http.Client{}` | Your own `*http.Client`, for proxies or tracing. | | `WithHeader(key, value)` | none | Extra header on every request, applied last. | | `WithRefreshToken(token)` | none | OAuth refresh token for automatic refresh. | | `WithOAuth(o)` | none | The `*OAuth` helper used for automatic refresh. | | `WithTokenRefreshHandler(fn)` | none | Called with the new `*TokenSet` after a refresh. Persist it here. | ## Verify an email `rv.Verify(ctx, email, opts)` checks one address with [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify) and returns a `*VerificationResult`. Branch on `Status` and read `SubStatus` for the reason. Go: ```go ctx := context.Background() result, err := rv.Verify(ctx, "deliverable@sandbox.rocketverifier.com", nil) if err != nil { log.Fatal(err) } switch result.Status { case rocketverifier.StatusDeliverable: // send case rocketverifier.StatusRisky: fmt.Println("review:", result.SubStatus) case rocketverifier.StatusUndeliverable: if result.DidYouMean != nil { fmt.Println("did you mean", *result.DidYouMean) } case rocketverifier.StatusUnknown: // free: check again later } ``` `VerifyOptions` has `IdempotencyKey` (a random key is used when empty) and `Timeout`, the server side verification timeout in seconds. The SDK accepts 5 to 60 and grows the HTTP timeout to cover it. Input without an `@` returns a validation error before any request is sent. The [reading results guide](https://docs.rocketverifier.com/results) explains every status and `sub_status`. ### Result fields | Field | Type | API field | | --- | --- | --- | | `Email`, `Status`, `Reason` | `string` | `email`, `status`, `reason` | | `SubStatus` | `string` | `sub_status`, `"none"` when not specific | | `Score` | `float64` | `score`, 0 to 100 | | `CatchAllVerdict` | `*string` | `catch_all_verdict` | | `DidYouMean` | `*string` | `did_you_mean` | | `VerifiedAt` | `*string` | `verified_at` | | `Provider` | `*string` | `provider` | | `Domain` | `DomainInfo` | `Name`, `AcceptAll *bool`, `Disposable bool`, `Free bool`, `AcceptAllConfidence`, `AcceptAllVerdict` | | `Account` | `*AccountInfo` | `Role bool`, `Disabled *bool`, `FullMailbox *bool` | | `DNS` | `*DNSInfo` | `Type`, `Record` | | `AuthenticationScore` | `*float64` | `authentication_score` | | `DeliverabilityTier` | `*string` | `deliverability_tier` | | `Toxic`, `Abuse` | `*string` | `"yes"`, `"no"` or `"unknown"` | | `SpamTrap` | `bool` | `spam_trap` | | `Activity`, `Evidence` | `map[string]any` | `activity`, `evidence` | | `Raw` | `json.RawMessage` | The full response body | `IsDeliverable()`, `IsUndeliverable()`, `IsRisky()` and `IsUnknown()` test the status. The `"yes"`, `"no"` and `"unknown"` flags become Go booleans: plain `bool` fields are `true` only for `"yes"`, and `*bool` fields are `nil` when the server reports `"unknown"`. Read any other field from `Raw`. ## Verify a list in bulk `rv.Batch` runs bulk jobs of up to 100,000 unique addresses. The [batch API reference](https://docs.rocketverifier.com/api/batch) covers the endpoints. Go: ```go job, err := rv.Batch.Create(ctx, &rocketverifier.BatchCreateParams{ Name: "October signups", Emails: []string{"deliverable@sandbox.rocketverifier.com", "undeliverable@sandbox.rocketverifier.com"}, }) if err != nil { log.Fatal(err) } done, err := rv.Batch.Wait(ctx, job.JobID, &rocketverifier.WaitOptions{ PollInterval: 3 * time.Second, OnProgress: func(j *rocketverifier.BatchJob) { fmt.Printf("%d/%d\n", j.ProcessedEmails, j.TotalEmails) }, }) ``` - **Create:** `Batch.Create(ctx, *BatchCreateParams{Emails, Name, IdempotencyKey})` returns `JobID`, `TotalEmails`, `EstimatedTimeSeconds`, `CreditsToUse` and `CreditsRemaining`. The limit applies to unique addresses. - **Wait:** `Batch.Wait(ctx, jobID, *WaitOptions)` polls every `PollInterval` (5 seconds) until the job is completed, failed or cancelled, or reaches `awaiting_confirmation`. Past `Timeout` (5 minutes) it returns an error with `Kind == KindTimeout`, and it stops early when `ctx` is done. - **Get:** `Batch.Get(ctx, jobID)` returns a `*BatchJob` with counts, `ProgressPercent` and timestamps. `IsFinished()` and `IsAwaitingConfirmation()` test the status. - **Progress:** `Batch.Progress(ctx, jobID)` returns a `*JobProgress` with `Total`, `Processed`, `Remaining`, `Percent`, `Counts`, `CountsByStatus`, `RatePerMinute` and `ETASeconds`. - **List:** `Batch.List(ctx, *ListOptions{Page, Limit, Status})` returns a `*JobsPage`. `Limit` defaults to 20, up to 100. - **Cancel:** `Batch.Delete(ctx, jobID)` or `Batch.Cancel(ctx, jobID)` returns `RefundedCredits` for unprocessed addresses. ### Read results `Batch.Results` returns one page, `Batch.Iterate` walks every row and `Batch.AllResults` returns them all in one slice. Go: ```go it := rv.Batch.Iterate(ctx, jobID, &rocketverifier.ResultsOptions{Classification: "valid"}) for it.Next() { r := it.Result() fmt.Println(r.Email, r.SubStatus) } if err := it.Err(); err != nil { log.Fatal(err) } ``` `ResultsOptions` has `Page`, `Limit` (100 for `Results`, 1000 for `Iterate` and `AllResults`, up to 1000) and `Classification`. Each `JobResult` has `Email`, `Classification`, `IsValid`, `IsDisposable`, `IsCatchAll`, `IsRoleBased`, `ConfidenceScore`, `SubStatus` and `VerifiedAt`. ### Download results Three methods download the full results of a completed job. `DownloadOptions` has `Format`, `Filter` (`deliverable`, `undeliverable`, `risky`, `unknown` or `send_safe`) and `IncludeOriginal`. Go: ```go csv, err := rv.Batch.Download(ctx, jobID, nil) // raw CSV bytes rows, err := rv.Batch.DownloadRows(ctx, jobID, &rocketverifier.DownloadOptions{Filter: "send_safe"}) data, err := rv.Batch.DownloadJSON(ctx, jobID, nil) // JobID, Results ``` `DownloadRows` parses the CSV with `ParseDownloadCSV`: boolean columns become `bool` and score columns become numbers. ## Upload a file `Batch.Upload(ctx, *UploadParams)` creates a job from a CSV, TSV, TXT or XLSX file of up to 50 MB, or from a public HTTPS URL. Set exactly one of `File`, `FilePath` or `SourceURL`. See [bulk upload](https://docs.rocketverifier.com/api/bulk-upload). Go: ```go up, err := rv.Batch.Upload(ctx, &rocketverifier.UploadParams{ FilePath: "contacts.csv", EmailColumn: "Work Email", Preview: true, }) if err != nil { log.Fatal(err) } preview, err := rv.Batch.Preview(ctx, up.JobID, false) for err == nil && preview.Pending { time.Sleep(2 * time.Second) preview, err = rv.Batch.Preview(ctx, up.JobID, false) } fmt.Println(preview.Preview["estimated_bounce_rate"]) confirmed, err := rv.Batch.Confirm(ctx, up.JobID, "") ``` - `UploadParams` also takes `File` (an `io.Reader`) with `Filename`, `Name`, `ColumnMapping`, `CallbackURL`, `ContentType` and `IdempotencyKey`. `EmailColumn` is a header name or a 0-based index. - `BatchUploadResult` has `JobID`, `Status`, `Preview`, `StatusURL`, `ProgressURL` and `CallbackSecret`, which is set once when you pass `CallbackURL`. - `Batch.Preview(ctx, jobID, refresh)` returns the free list health estimate as a map, with `Pending` set while it is computing. - `Batch.Confirm(ctx, jobID, idempotencyKey)` charges and starts the job. A job is never charged twice, so it is safe to retry. ## Check a domain, credits and account Go: ```go info, err := rv.Domain.Check(ctx, "northwind.io") // Domain, MXRecords, Provider, Disposable, HasValidMX credits, err := rv.Credits(ctx) // Credits, UsedToday, UsedThisMonth me, err := rv.Me(ctx) // Email, AccountType, Organization, Credits, AuthType, Scopes, App ``` `Me` calls [`GET /v1/me`](https://docs.rocketverifier.com/api/account). `me.IsOAuth()` is true for OAuth tokens. ## Manage monitors `rv.Monitors` schedules list health re-verification and SPF, DKIM and DMARC checks. See the [monitors API](https://docs.rocketverifier.com/api/monitors). Go: ```go m, err := rv.Monitors.Create(ctx, &rocketverifier.MonitorCreateParams{ Name: "Brand domain", Type: rocketverifier.MonitorTypeDomainAuth, Domain: "northwind.io", }) ``` | Method | What it does | | --- | --- | | `Create(ctx, *MonitorCreateParams)` | `Frequency` defaults to `weekly`, `AlertThreshold` to 5. `domain_auth` needs `Domain`; `list_health` needs `Emails`. | | `List(ctx)`, `Get(ctx, id)` | Return `Monitor` values. | | `Update(ctx, id, *MonitorUpdateParams)` | Pointer fields left `nil` are unchanged. | | `Delete(ctx, id)` | Removes the monitor. | | `Runs(ctx, id, *PageOptions)` | A `*MonitorRunsPage`, most recent first. | | `RunNow(ctx, id, idempotencyKey)` | Runs it immediately. `list_health` runs cost 1 credit per address. | ## Manage webhook endpoints `rv.Webhooks` registers HTTPS endpoints for events such as `job.completed`. It needs the `webhooks:manage` scope. See the [webhooks API](https://docs.rocketverifier.com/api/webhooks). Go: ```go hook, err := rv.Webhooks.Create(ctx, &rocketverifier.WebhookCreateParams{ URL: "https://northwind.io/hooks/rocketverifier", Events: []string{rocketverifier.EventJobCompleted, rocketverifier.EventJobFailed}, }) // Store hook.Secret now: it is shown only once. ``` The service also has `ListEvents`, `List`, `Get`, `Update` (with `*WebhookUpdateParams`), `Delete`, `Test`, `Logs` (with `*WebhookLogsOptions{Page, Limit, Status}`) and `RotateSecret`. Event names are exported as `EventJobCompleted`, `EventJobFailed`, `EventCreditsLow`, `EventCreditsDepleted`, `EventEmailVerified` and `EventMonitorAlert`. ## Verify webhook signatures `ConstructEvent` checks the `X-RocketVerifier-Signature` header and the timestamp, then returns the event. Pass the raw body exactly as received. Go: ```go http.HandleFunc("/hooks/rocketverifier", func(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(io.LimitReader(r.Body, 1<<20)) header := strings.Join(r.Header.Values(rocketverifier.SignatureHeader), ",") event, err := rocketverifier.ConstructEvent(body, header, os.Getenv("ROCKETVERIFIER_WEBHOOK_SECRET")) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } if event.Event == rocketverifier.EventJobCompleted { var data struct { JobID string `json:"job_id"` } _ = event.DecodeData(&data) log.Printf("job %s finished", data.JobID) } w.WriteHeader(http.StatusOK) }) ``` - `VerifySignature(rawBody, header, secret, opts...)` returns `nil` or a `*WebhookSignatureError` whose `Reason` is `missing_secret`, `missing_header`, `malformed_header`, `timestamp_out_of_tolerance` or `signature_mismatch`. `ConstructEvent` adds `invalid_json`. - `WithTolerance(d)` changes the 300 second window; `WithNow(t)` fixes the clock in tests. - `GenerateSignatureHeader(rawBody, secret, timestamp)` builds a valid header for testing your endpoint. ## Act for a user with OAuth `NewOAuth` runs the RocketVerifier Connect authorization code flow with PKCE; `NewWithAccessToken` calls the API for the connected user. The [OAuth guide](https://docs.rocketverifier.com/oauth) covers app registration. Go: ```go oauth, err := rocketverifier.NewOAuth(rocketverifier.OAuthConfig{ ClientID: os.Getenv("RV_CLIENT_ID"), ClientSecret: os.Getenv("RV_CLIENT_SECRET"), RedirectURI: "https://northwind.io/rocketverifier/callback", }) auth, err := oauth.AuthorizeURL(rocketverifier.AuthorizeParams{Scopes: []string{"verify:bulk", "account:read"}}) // store auth.State and auth.CodeVerifier, redirect to auth.URL tokens, err := oauth.ExchangeCode(ctx, code, auth.CodeVerifier, "") userRV, err := rocketverifier.NewWithAccessToken(tokens.AccessToken, rocketverifier.WithRefreshToken(tokens.RefreshToken), rocketverifier.WithOAuth(oauth), rocketverifier.WithTokenRefreshHandler(func(ctx context.Context, t *rocketverifier.TokenSet) error { return saveTokens(ctx, userID, t) }), ) ``` - `OAuthConfig` also takes `Issuer` (default `https://app.rocketverifier.com`), `TokenEndpointAuthMethod` (default `client_secret_basic`), `HTTPClient` and `Timeout`. Leave `ClientSecret` empty for public clients. - `OAuth` has `AuthorizeURL`, `ExchangeCode`, `Refresh`, `Revoke` and `Introspect`. `TokenSet` holds `AccessToken`, `RefreshToken`, `TokenType`, `ExpiresIn`, `ExpiresAt` (`time.Time`) and `Scopes`. - On a 401 `invalid_token` the client refreshes once, retries and calls your handler. Without refresh configured, it returns an error matching `ErrInvalidToken`. A rejected refresh token returns an `*OAuthError` with `ErrorCode == "invalid_grant"`. - `rv.SetTokens(accessToken, refreshToken)` swaps in tokens refreshed elsewhere. ## Handle errors Every API failure is a `*rocketverifier.Error` with `Kind`, `Code`, `StatusCode`, `Message`, `Details`, `RetryAfter` and `Err`. Match it with `errors.Is` and the sentinel errors. | Sentinel | `Kind` | Returned when | | --- | --- | --- | | `ErrAuthentication` | `KindAuthentication` | 401. Also matches invalid token errors. | | `ErrInvalidToken` | `KindInvalidToken` | 401 `invalid_token` for an OAuth token that cannot be refreshed. | | `ErrInsufficientCredits` | `KindInsufficientCredits` | 402, or code `insufficient_credits` (including the 403 at zero balance). | | `ErrRateLimited` | `KindRateLimit` | 429 after all retries. `RetryAfter` holds the seconds. | | `ErrValidation` | `KindValidation` | 400 or 422, or input rejected before sending. | | `ErrPermissionDenied` | `KindPermissionDenied` | 403, such as a missing scope. | | `ErrNotFound` | `KindNotFound` | 404. | | `ErrTimeout` | `KindTimeout` | The request or `Batch.Wait` timed out. `StatusCode` is 408. | | `ErrNetwork` | `KindNetwork` | The connection failed. `StatusCode` is 0. | Go: ```go _, err := rv.Verify(ctx, "maya@northwind.io", nil) var apiErr *rocketverifier.Error switch { case errors.Is(err, rocketverifier.ErrInsufficientCredits): // top up case errors.As(err, &apiErr) && apiErr.Kind == rocketverifier.KindRateLimit: time.Sleep(time.Duration(apiErr.RetryAfter) * time.Second) case err != nil: log.Fatal(err) } ``` The [errors reference](https://docs.rocketverifier.com/errors) lists every API error code. ## Retries and timeouts - **Rate limits (429):** retried up to `WithMaxRetries` times, waiting for the `Retry-After` seconds, or 60 seconds when the header is missing. See [rate limits](https://docs.rocketverifier.com/rate-limits). - **Timeouts and network errors:** retried with 1, 2 and 3 second waits. - **Other errors:** returned straight away. - **Context:** a cancelled or expired `ctx` stops the call and any wait between retries. - **Idempotency:** every POST, PUT and PATCH sends an `Idempotency-Key` reused across retries of that call. ## Next steps - [Reading results](https://docs.rocketverifier.com/results) Every status and sub_status, what it costs and what to do with it. - [All SDKs](https://docs.rocketverifier.com/sdks) Compare the Node.js, Python, Go, PHP and Ruby libraries and the CLI. ## Frequently asked questions ### Does the Go SDK have dependencies? No. It uses only the Go standard library and needs Go 1.21 or later. ### Is the client safe for concurrent use? Yes. Create one `*rocketverifier.Client` and share it across goroutines. OAuth refresh is serialized, so concurrent calls share a single refresh. ### How do I check for a specific error? Use `errors.Is(err, rocketverifier.ErrInsufficientCredits)` and the other sentinel errors, or `errors.As` into `*rocketverifier.Error` to read `Code`, `StatusCode` and `RetryAfter`. ### Which errors does the SDK retry? Rate limits (429), timeouts and network errors, up to `WithMaxRetries` times (3 by default). Other 4xx and 5xx responses are returned straight away. --- # PHP SDK Source: https://docs.rocketverifier.com/sdks/php > Run composer require rocketverifier/sdk, create new RocketVerifier\RocketVerifier($apiKey) and call $rv->verify($email). The package needs only PHP 8.1 and ext-curl, returns readonly typed models with yes and no flags as booleans, and retries safely with a stable Idempotency-Key. `rocketverifier/sdk` is the official PHP library for the RocketVerifier API. It covers real-time verification, bulk jobs from a list or a file, progress and downloads, webhooks, monitors, credits and RocketVerifier Connect OAuth, with no Composer runtime dependencies. ## Install the SDK Install with Composer. Classes live in the `RocketVerifier` namespace and load through PSR-4. Terminal: ```bash composer require rocketverifier/sdk ``` ## Create a client Pass your API key as the first argument and any options as an array. Read the key from `ROCKETVERIFIER_API_KEY` so it never lands in source control. PHP: ```php 15, 'max_retries' => 5, ]); ``` The constructor throws `AuthenticationException` without a credential and `ValidationException` for an unknown option. Live keys start with `rv_live_`; sandbox keys start with `rv_test_` and accept only [sandbox addresses](https://docs.rocketverifier.com/sandbox). See [authentication](https://docs.rocketverifier.com/authentication). | Option | Default | What it does | | --- | --- | --- | | `api_key` | none | The API key, when the first argument is `null`. | | `access_token` | none | An OAuth access token (`rv_at_...`). Calls run on the connected user's credits. | | `refresh_token` | none | OAuth refresh token for automatic refresh. | | `oauth` | none | A `RocketVerifier\OAuth` instance used for automatic refresh. | | `on_token_refresh` | none | `callable(TokenSet)` called after a refresh. Persist the new token here. | | `base_url` | `https://api.rocketverifier.com` | API base URL. | | `timeout` | `30` | Seconds per request. | | `max_retries` | `3` | Retries on 429, timeouts and network errors. `0` turns retries off. | | `headers` | `[]` | Extra headers on every request, applied last. | | `http_client` | `CurlHttpClient` | Any `HttpClientInterface` implementation. | ## Verify an email `$rv->verify($email, $idempotencyKey = null, $timeout = null)` checks one address with [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify) and returns a `VerificationResult`. Branch on `status` and read `subStatus` for the reason. PHP: ```php $result = $rv->verify('deliverable@sandbox.rocketverifier.com'); switch ($result->status) { case 'deliverable': break; // send case 'risky': echo "Review: {$result->subStatus} {$result->catchAllVerdict}\n"; break; case 'undeliverable': echo "Remove. Suggestion: {$result->didYouMean}\n"; break; case 'unknown': break; // free: check again later } ``` `$timeout` is the server side verification timeout in seconds. The SDK accepts 5 to 60 and grows the HTTP timeout to cover it. Input without an `@` throws `ValidationException` before any request is sent. The [reading results guide](https://docs.rocketverifier.com/results) explains every status and `sub_status`. ### Result fields `VerificationResult` exposes readonly camelCase properties. | Property | Type | API field | | --- | --- | --- | | `email`, `status`, `reason` | `string` | `email`, `status`, `reason` | | `subStatus` | `string` | `sub_status`, `"none"` when not specific | | `score` | `int\|float\|null` | `score` | | `catchAllVerdict` | `?string` | `catch_all_verdict` | | `didYouMean` | `?string` | `did_you_mean` | | `verifiedAt` | `?string` | `verified_at` | | `provider` | `?string` | `provider` | | `domain` | `DomainInfo` | `name`, `acceptAll` (`?bool`), `disposable` (`bool`), `free` (`bool`), `acceptAllConfidence`, `acceptAllVerdict` | | `account` | `?AccountInfo` | `role` (`bool`), `disabled` (`?bool`), `fullMailbox` (`?bool`) | | `dns` | `?array` | `dns` | | `authenticationScore` | `int\|float\|null` | `authentication_score` | | `deliverabilityTier` | `?string` | `deliverability_tier` | | `toxic`, `abuse` | `?string` | `"yes"`, `"no"` or `"unknown"` | | `spamTrap` | `?bool` | `spam_trap` | | `activity`, `evidence` | `?array` | `activity`, `evidence` | | `raw` | `array` | The full response | `isDeliverable()`, `isUndeliverable()`, `isRisky()` and `isUnknown()` test the status. Flags become real booleans: `bool` properties are `true` only for `"yes"`, and `?bool` properties are `null` when the server reports `"unknown"`. ## Verify a list in bulk `$rv->batch` runs bulk jobs of up to 100,000 unique addresses. The [batch API reference](https://docs.rocketverifier.com/api/batch) covers the endpoints. PHP: ```php $job = $rv->batch->create( ['deliverable@sandbox.rocketverifier.com', 'undeliverable@sandbox.rocketverifier.com'], 'October signups' ); $done = $rv->batch->wait($job->jobId, pollInterval: 3, onProgress: function ($j) { echo "{$j->processedEmails}/{$j->totalEmails}\n"; }); $rows = $rv->batch->download($done->id, parse: true, filter: 'send_safe'); ``` | Method | Returns | | --- | --- | | `create(array $emails, ?string $name = null, ?string $idempotencyKey = null)` | `BatchCreateResult` with `jobId`, `totalEmails`, `estimatedTimeSeconds`, `creditsToUse`, `creditsRemaining` | | `get($jobId)` | `BatchJob` with counts, `progressPercent` and timestamps | | `progress($jobId)` | `JobProgress` with `percent`, `counts`, `countsByStatus`, `ratePerMinute`, `etaSeconds` | | `wait($jobId, $pollInterval = 5, $timeout = 300, $onProgress = null)` | The final `BatchJob`. Seconds. Throws code `timeout` past `$timeout`. | | `results($jobId, $page = 1, $limit = 100, $classification = null)` | `JobResultsPage`. `limit` up to 1000. | | `iterateResults($jobId, $pageSize = 1000, $classification = null)` | A `Generator` of `JobResult` | | `allResults($jobId, $classification = null)` | `list` | | `download($jobId, $format = 'csv', $parse = false, $filter = null, $includeOriginal = false)` | CSV string, parsed rows, or the decoded JSON array | | `list($page = 1, $limit = 20, $status = null)` | `JobsPage`. `limit` up to 100. | | `delete($jobId)`, `cancel($jobId)` | `JobDeleteResult` with `refundedCredits` | `wait()` also returns when a previewed upload reaches `awaiting_confirmation`. `download()` filters by `deliverable`, `undeliverable`, `risky`, `unknown` or `send_safe`, and `includeOriginal` joins upload jobs with your file's own columns. ## Upload a file `$rv->batch->upload([...])` creates a job from a CSV, TSV, TXT or XLSX file of up to 50 MB, or from a public HTTPS URL. Pass exactly one of `file` or `source_url`. See [bulk upload](https://docs.rocketverifier.com/api/bulk-upload). PHP: ```php $upload = $rv->batch->upload([ 'file' => 'contacts.csv', 'email_column' => 'Work Email', 'preview' => true, ]); $res = $rv->batch->preview($upload->jobId); while ($res->pending) { sleep(2); $res = $rv->batch->preview($upload->jobId); } echo $res->preview['estimated_bounce_rate'], "\n"; $confirmed = $rv->batch->confirm($upload->jobId); echo $confirmed->creditsCharged, "\n"; ``` - `file` is a local path, an open stream resource, or the bytes as a string (then pass `filename`). - Other keys: `filename`, `source_url`, `name`, `email_column`, `column_mapping` (array), `preview`, `callback_url`, `content_type` and `idempotency_key`. - `BatchUploadResult` has `jobId`, `status`, `preview`, `statusUrl`, `progressUrl` and `callbackSecret`, set once when you pass `callback_url`. - `confirm()` charges and starts the job. A job is never charged twice, so it is safe to retry. ## Check a domain, credits and account PHP: ```php $info = $rv->domain->check('northwind.io'); // domain, mxRecords, provider, disposable, hasValidMx $credits = $rv->getCredits(); // credits, usedToday, usedThisMonth $me = $rv->getMe(); // email, accountType, organization, credits, authType, scopes, app ``` `getMe()` calls [`GET /v1/me`](https://docs.rocketverifier.com/api/account). ## Manage monitors `$rv->monitors` schedules list health re-verification and SPF, DKIM and DMARC checks. See the [monitors API](https://docs.rocketverifier.com/api/monitors). PHP: ```php $monitor = $rv->monitors->create([ 'name' => 'Brand domain', 'type' => 'domain_auth', 'domain' => 'northwind.io', ]); $rv->monitors->update($monitor->id, ['frequency' => 'daily']); ``` - `create()` takes `name`, `type`, `frequency` (default `weekly`), `domain`, `emails`, `alert_threshold` (default 5) and `idempotency_key`. - `update($id, $fields)` takes `name`, `frequency`, `is_active`, `alert_threshold`, `domain` and `emails`; `null` values are left unchanged. - `list()`, `get($id)`, `delete($id)`, `runs($id, $page = 1, $limit = 20)` and `runNow($id, $idempotencyKey = null)` complete the set. `list_health` runs cost 1 credit per address. ## Manage webhook endpoints `$rv->webhooks` registers HTTPS endpoints for events such as `job.completed`. It needs the `webhooks:manage` scope. See the [webhooks API](https://docs.rocketverifier.com/api/webhooks). PHP: ```php $hook = $rv->webhooks->create( 'https://northwind.io/hooks/rocketverifier', events: ['job.completed', 'job.failed', 'credits.low'] ); // Store $hook->secret now: it is shown only once. ``` The resource also has `listEvents()`, `list()`, `get($id)`, `update($id, ['name' => ..., 'url' => ..., 'events' => ..., 'is_active' => ...])`, `delete($id)`, `test($id)`, `logs($id, $page = 1, $limit = 50, $status = null)` and `rotateSecret($id)`. ## Verify webhook signatures `Webhook::constructEvent()` checks the `X-RocketVerifier-Signature` header and the timestamp, then returns the decoded event array. Pass the raw body exactly as received. PHP: ```php use RocketVerifier\Webhook; use RocketVerifier\Exception\WebhookSignatureException; try { $event = Webhook::constructEvent( file_get_contents('php://input'), $_SERVER['HTTP_X_ROCKETVERIFIER_SIGNATURE'] ?? null, getenv('ROCKETVERIFIER_WEBHOOK_SECRET') ); } catch (WebhookSignatureException $e) { http_response_code(400); exit($e->reason); } if ($event['event'] === 'job.completed') { error_log('Job ' . $event['data']['job_id'] . ' finished'); } http_response_code(200); ``` - `Webhook::verifySignature($rawBody, $header, $secret, $tolerance = 300, $now = null)` returns a `bool`. - `WebhookSignatureException::$reason` is `missing_secret`, `missing_header`, `malformed_header`, `timestamp_out_of_tolerance`, `signature_mismatch` or `invalid_json`. - `Webhook::generateSignatureHeader($rawBody, $secret)` builds a valid header for testing your endpoint. ## Act for a user with OAuth `RocketVerifier\OAuth` runs the RocketVerifier Connect authorization code flow with PKCE. The [OAuth guide](https://docs.rocketverifier.com/oauth) covers app registration. PHP: ```php use RocketVerifier\OAuth; use RocketVerifier\RocketVerifier; $oauth = new OAuth( getenv('RV_CLIENT_ID'), getenv('RV_CLIENT_SECRET'), 'https://northwind.io/rocketverifier/callback' ); $auth = $oauth->authorizeUrl(['verify:bulk', 'account:read']); $_SESSION['rv_state'] = $auth->state; $_SESSION['rv_verifier'] = $auth->codeVerifier; header('Location: ' . $auth->url); // On the callback, after checking state: $tokens = $oauth->exchangeCode($_GET['code'], $_SESSION['rv_verifier']); $userRv = new RocketVerifier(null, [ 'access_token' => $tokens->accessToken, 'refresh_token' => $tokens->refreshToken, 'oauth' => $oauth, 'on_token_refresh' => fn ($t) => saveTokens($userId, $t), ]); ``` - `new OAuth($clientId, $clientSecret = null, $redirectUri = null, $issuer, $tokenEndpointAuthMethod = 'client_secret_basic', $httpClient = null, $timeout = 30)`. Omit the secret for public clients. - `authorizeUrl($scopes, $redirectUri, $state, $codeVerifier, $resource, $prompt)`, `exchangeCode()`, `refresh()`, `revoke($token, $tokenTypeHint)` and `introspect()` complete the flow. `OAuth::generatePkcePair()` and `OAuth::SCOPES` are available for custom flows. - `TokenSet` has `accessToken`, `refreshToken`, `tokenType`, `expiresIn`, `expiresAt` (Unix seconds) and `scopes`. - On a 401 `invalid_token` the client refreshes once, retries and calls `on_token_refresh`. Without refresh configured it throws `InvalidTokenException`. A rejected refresh token throws `OAuthException` with `$error === 'invalid_grant'`. - `$rv->setTokens($accessToken, $refreshToken)` swaps in tokens refreshed elsewhere. ## Handle errors Every exception extends `RocketVerifier\Exception\RocketVerifierException`, with `getErrorCode()`, `getStatusCode()` and `getDetails()`. | Exception | Thrown when | | --- | --- | | `AuthenticationException` | 401, or no credential passed. | | `InvalidTokenException` | 401 `invalid_token` for an OAuth token that cannot be refreshed. | | `InsufficientCreditsException` | 402, or code `insufficient_credits` (including the 403 at zero balance). | | `RateLimitException` | 429 after all retries. `$retryAfter` holds the seconds. | | `ValidationException` | 400 or 422, or input rejected before sending. | | `PermissionDeniedException` | 403, such as a missing scope or an IP allowlist. | | `NotFoundException` | 404. | | `WebhookSignatureException` | A delivery fails verification. | | `OAuthException` | The token, revoke or introspect endpoint returns an error. | | `RocketVerifierException` | Every other status, plus timeouts (`timeout`) and network failures (`network_error`). | PHP: ```php use RocketVerifier\Exception\InsufficientCreditsException; use RocketVerifier\Exception\RateLimitException; use RocketVerifier\Exception\RocketVerifierException; try { $rv->verify('maya@northwind.io'); } catch (RateLimitException $e) { sleep($e->retryAfter ?? 60); } catch (InsufficientCreditsException $e) { // top up } catch (RocketVerifierException $e) { error_log($e->getErrorCode() . ': ' . $e->getMessage()); } ``` The [errors reference](https://docs.rocketverifier.com/errors) lists every API error code. ## Retries and timeouts - **Rate limits (429):** retried up to `max_retries` times, waiting for the `Retry-After` seconds, or 60 seconds when the header is missing. See [rate limits](https://docs.rocketverifier.com/rate-limits). - **Timeouts and network errors:** retried with 1, 2 and 3 second waits. - **Other errors:** thrown straight away. - **Idempotency:** every POST, PUT and PATCH sends an `Idempotency-Key` reused across retries of that call. ## Next steps - [Reading results](https://docs.rocketverifier.com/results) Every status and sub_status, what it costs and what to do with it. - [All SDKs](https://docs.rocketverifier.com/sdks) Compare the Node.js, Python, Go, PHP and Ruby libraries and the CLI. ## Frequently asked questions ### Which PHP version does the SDK need? PHP 8.1 or later with the curl, json and hash extensions. There are no Composer runtime dependencies. ### Can I use Guzzle or my framework's HTTP client? Yes. Implement `RocketVerifier\Http\HttpClientInterface` (one `send` method) and pass it as the `http_client` option. The default is the bundled cURL client. ### Which errors does the SDK retry? Rate limits (429), timeouts and network errors, up to `max_retries` times (3 by default). Other 4xx and 5xx responses throw straight away. ### Why compare flags with booleans instead of strings? The SDK converts the API's `"yes"` and `"no"` strings, so `$result->domain->disposable` is a real `bool`. The string `"no"` is truthy in PHP, which is why the conversion matters. --- # Ruby SDK Source: https://docs.rocketverifier.com/sdks/ruby > Run gem install rocketverifier, create RocketVerifier::Client.new(api_key) and call rv.verify(email). The gem uses only the Ruby standard library, converts yes and no flags to booleans, and retries safely with a stable Idempotency-Key. The `rocketverifier` gem is the official Ruby library for the RocketVerifier API. It covers real-time verification, bulk jobs from a list or a file, progress and downloads, webhooks, monitors, credits and RocketVerifier Connect OAuth. ## Install the gem Terminal: ```bash gem install rocketverifier # or in your Gemfile: # gem "rocketverifier" ``` ## Create a client Pass your API key as the first argument and any options as keywords. Read the key from `ROCKETVERIFIER_API_KEY` so it never lands in source control. Ruby: ```ruby require "rocketverifier" rv = RocketVerifier::Client.new(ENV.fetch("ROCKETVERIFIER_API_KEY"), timeout: 15, max_retries: 5) ``` The constructor raises `RocketVerifier::AuthenticationError` without a credential. Live keys start with `rv_live_`; sandbox keys start with `rv_test_` and accept only [sandbox addresses](https://docs.rocketverifier.com/sandbox). See [authentication](https://docs.rocketverifier.com/authentication). | Keyword | Default | What it does | | --- | --- | --- | | `api_key:` | none | The API key, when no positional argument is given. | | `access_token:` | none | An OAuth access token (`rv_at_...`). Calls run on the connected user's credits. | | `refresh_token:` | none | OAuth refresh token for automatic refresh. | | `oauth:` | none | A `RocketVerifier::OAuth` instance used for automatic refresh. | | `on_token_refresh:` | none | Callable that receives the new `TokenSet`. Persist it here. | | `base_url:` | `https://api.rocketverifier.com` | API base URL. | | `timeout:` | `30` | Seconds for open, read and write. | | `max_retries:` | `3` | Retries on 429, timeouts and network errors. `0` turns retries off. | | `headers:` | `{}` | Extra headers on every request, applied last. | ## Verify an email `rv.verify(email, idempotency_key: nil, timeout: nil)` checks one address with [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify) and returns a `VerificationResult`. Branch on `status` and read `sub_status` for the reason. Ruby: ```ruby result = rv.verify("deliverable@sandbox.rocketverifier.com") case result.status when "deliverable" then send_to(result.email) when "risky" then review(result.email, result.sub_status, result.catch_all_verdict) when "undeliverable" then puts "Remove. Suggestion: #{result.did_you_mean}" when "unknown" then retry_later(result.email) # free end ``` `timeout:` is the server side verification timeout in seconds. The gem accepts 5 to 60 and grows the HTTP timeout to cover it. Input without an `@` raises `ValidationError` before any request is sent. The [reading results guide](https://docs.rocketverifier.com/results) explains every status and `sub_status`. ### Result fields `VerificationResult` has readers named after the API's snake_case fields: `email`, `status`, `reason`, `sub_status`, `score`, `provider`, `catch_all_verdict`, `verified_at`, `did_you_mean`, `domain`, `account`, `dns`, `authentication_score`, `deliverability_tier`, `toxic`, `abuse`, `spam_trap`, `activity` and `evidence`. `deliverable?`, `undeliverable?`, `risky?` and `unknown?` test the status. - `domain.disposable`, `domain.free` and `account.role` are `true` only for `"yes"`. - `domain.accept_all`, `account.disabled` and `account.full_mailbox` are `true`, `false` or `nil` when the server reports `"unknown"`. - `spam_trap` is a boolean; `toxic` and `abuse` keep the original string. - Every model has `raw`, `to_h` and `[]`, so `result["retry_after"]` reads any field the gem does not name. ## Verify a list in bulk `rv.batch` runs bulk jobs of up to 100,000 unique addresses. The [batch API reference](https://docs.rocketverifier.com/api/batch) covers the endpoints. Ruby: ```ruby job = rv.batch.create( emails: ["deliverable@sandbox.rocketverifier.com", "undeliverable@sandbox.rocketverifier.com"], name: "October signups" ) done = rv.batch.wait(job.job_id, poll_interval: 3) do |j| puts "#{j.processed_emails}/#{j.total_emails}" end rows = rv.batch.download(done.id, parse: true, filter: "send_safe") ``` | Method | Returns | | --- | --- | | `create(emails:, name: nil, idempotency_key: nil)` | `BatchCreateResult` with `job_id`, `total_emails`, `estimated_time_seconds`, `credits_to_use`, `credits_remaining` | | `get(job_id)` | `BatchJob` with counts, `progress_percent`, timestamps, `finished?` and `awaiting_confirmation?` | | `progress(job_id)` | `JobProgress` with `percent`, `counts`, `counts_by_status`, `rate_per_minute`, `eta_seconds` | | `wait(job_id, poll_interval: 5, timeout: 300) { \|job\| }` | The final `BatchJob`. Yields every snapshot. Raises code `timeout` past `timeout` seconds. | | `results(job_id, page: 1, limit: 100, classification: nil)` | `JobResultsPage`. `limit` up to 1000. | | `each_result(job_id, page_size: 1000, classification: nil)` | Yields every `JobResult`, or returns an `Enumerator` without a block | | `all_results(job_id, classification: nil)` | `Array` of `JobResult` | | `download(job_id, format: "csv", parse: false, filter: nil, include_original: false)` | CSV string, parsed row hashes, or the parsed JSON | | `list(page: 1, limit: 20, status: nil)` | `JobsPage`. `limit` up to 100. | | `delete(job_id)`, `cancel(job_id)` | `JobDeleteResult` with `refunded_credits` | `wait` also returns when a previewed upload reaches `awaiting_confirmation`. `download` filters by `deliverable`, `undeliverable`, `risky`, `unknown` or `send_safe`, and `include_original: true` joins upload jobs with your file's own columns. ## Upload a file `rv.batch.upload` creates a job from a CSV, TSV, TXT or XLSX file of up to 50 MB, or from a public HTTPS URL. Pass exactly one of `file:` or `source_url:`. See [bulk upload](https://docs.rocketverifier.com/api/bulk-upload). Ruby: ```ruby upload = rv.batch.upload(file: "contacts.csv", email_column: "Work Email", preview: true) res = rv.batch.preview(upload.job_id) while res.pending? sleep 2 res = rv.batch.preview(upload.job_id) end puts res.preview["estimated_bounce_rate"] confirmed = rv.batch.confirm(upload.job_id) puts confirmed.credits_charged ``` - `file:` is a path, an IO, or a string of bytes (then pass `filename:`). Other keywords: `filename:`, `source_url:`, `name:`, `email_column:`, `column_mapping:`, `preview:`, `callback_url:`, `content_type:` and `idempotency_key:`. - `BatchUploadResult` has `job_id`, `status`, `preview`, `status_url`, `progress_url` and `callback_secret`, set once when you pass `callback_url:`. - `confirm(job_id, idempotency_key: nil)` charges and starts the job. A job is never charged twice, so it is safe to retry. ## Check a domain, credits and account Ruby: ```ruby info = rv.domain.check("northwind.io") # domain, mx_records, provider, disposable, has_valid_mx credits = rv.credits # credits, used_today, used_this_month (alias get_credits) me = rv.me # email, account_type, organization, credits, auth_type, scopes, app ``` `rv.me` (alias `get_me`) calls [`GET /v1/me`](https://docs.rocketverifier.com/api/account). `me.oauth?` is true for OAuth tokens. ## Manage monitors `rv.monitors` schedules list health re-verification and SPF, DKIM and DMARC checks. See the [monitors API](https://docs.rocketverifier.com/api/monitors). Ruby: ```ruby monitor = rv.monitors.create(name: "Brand domain", type: "domain_auth", domain: "northwind.io") rv.monitors.update(monitor.id, frequency: "daily") ``` - `create(name:, type:, frequency: "weekly", domain: nil, emails: nil, alert_threshold: 5, idempotency_key: nil)`. `domain_auth` needs `domain:`; `list_health` needs `emails:`. - `update(id, name:, frequency:, is_active:, alert_threshold:, domain:, emails:)` changes only what you pass. - `list`, `get(id)`, `delete(id)`, `runs(id, page: 1, limit: 20)` and `run_now(id, idempotency_key: nil)` complete the set. `list_health` runs cost 1 credit per address. ## Manage webhook endpoints `rv.webhooks` registers HTTPS endpoints for events such as `job.completed`. It needs the `webhooks:manage` scope. See the [webhooks API](https://docs.rocketverifier.com/api/webhooks). Ruby: ```ruby hook = rv.webhooks.create( url: "https://northwind.io/hooks/rocketverifier", events: %w[job.completed job.failed credits.low] ) # Store hook.secret now: it is shown only once. ``` The resource also has `list_events`, `list`, `get(id)`, `update(id, name:, url:, events:, is_active:)`, `delete(id)`, `test(id)`, `logs(id, page: 1, limit: 50, status: nil)` and `rotate_secret(id)`. ## Verify webhook signatures `RocketVerifier::Webhook.construct_event` checks the `X-RocketVerifier-Signature` header and the timestamp, then returns the parsed event hash. Pass the raw body exactly as received. Ruby: ```ruby post "/hooks/rocketverifier" do event = RocketVerifier::Webhook.construct_event( request.body.read, request.get_header("HTTP_X_ROCKETVERIFIER_SIGNATURE"), ENV.fetch("ROCKETVERIFIER_WEBHOOK_SECRET") ) puts "Job #{event['data']['job_id']} finished" if event["event"] == "job.completed" 200 rescue RocketVerifier::WebhookSignatureError => e halt 400, e.reason end ``` - `Webhook.verify_signature(raw_body, header, secret, tolerance: 300, now: nil)` returns `true` or `false`. - `WebhookSignatureError#reason` is `missing_secret`, `missing_header`, `malformed_header`, `timestamp_out_of_tolerance`, `signature_mismatch` or `invalid_json`. - `Webhook.generate_signature_header(raw_body, secret)` builds a valid header for testing your endpoint. ## Act for a user with OAuth `RocketVerifier::OAuth` runs the RocketVerifier Connect authorization code flow with PKCE. The [OAuth guide](https://docs.rocketverifier.com/oauth) covers app registration. Ruby: ```ruby oauth = RocketVerifier::OAuth.new( client_id: ENV.fetch("RV_CLIENT_ID"), client_secret: ENV.fetch("RV_CLIENT_SECRET"), redirect_uri: "https://northwind.io/rocketverifier/callback" ) auth = oauth.authorize_url(scopes: %w[verify:bulk account:read]) session[:rv_state] = auth.state session[:rv_verifier] = auth.code_verifier redirect auth.url # On the callback, after checking state: tokens = oauth.exchange_code(code: params[:code], code_verifier: session[:rv_verifier]) user_rv = RocketVerifier::Client.new( access_token: tokens.access_token, refresh_token: tokens.refresh_token, oauth: oauth, on_token_refresh: ->(t) { save_tokens(user_id, t) } ) ``` - `OAuth.new(client_id:, client_secret: nil, redirect_uri: nil, issuer:, token_endpoint_auth_method: "client_secret_basic", timeout: 30)`. Omit the secret for public clients. - `authorize_url`, `exchange_code`, `refresh(refresh_token)`, `revoke(token, token_type_hint: nil)` and `introspect(token)` complete the flow. `OAuth.generate_pkce_pair` and `OAuth::SCOPES` are available for custom flows. - `TokenSet` has `access_token`, `refresh_token`, `token_type`, `expires_in`, `expires_at` (Unix seconds) and `scopes`. - On a 401 `invalid_token` the client refreshes once, retries and calls `on_token_refresh`. Without refresh configured it raises `InvalidTokenError`. A rejected refresh token raises `OAuthError` with `error == "invalid_grant"`. - `rv.set_tokens(access_token:, refresh_token:)` swaps in tokens refreshed elsewhere. ## Handle errors Every error extends `RocketVerifier::Error`, with `code`, `status_code` and `details`. | Error | Raised when | | --- | --- | | `AuthenticationError` | 401, or no credential passed. | | `InvalidTokenError` | 401 `invalid_token` for an OAuth token that cannot be refreshed. | | `InsufficientCreditsError` | 402, or code `insufficient_credits` (including the 403 at zero balance). | | `RateLimitError` | 429 after all retries. `retry_after` holds the seconds. | | `ValidationError` | 400 or 422, or input rejected before sending. | | `PermissionDeniedError` | 403, such as a missing scope or an IP allowlist. | | `NotFoundError` | 404. | | `WebhookSignatureError` | A delivery fails verification. | | `OAuthError` | The token, revoke or introspect endpoint returns an error. | | `Error` | Every other status, plus timeouts (`timeout`) and network failures (`network_error`). | Ruby: ```ruby begin rv.verify("maya@northwind.io") rescue RocketVerifier::RateLimitError => e sleep(e.retry_after || 60) rescue RocketVerifier::InsufficientCreditsError notify_billing rescue RocketVerifier::Error => e warn "#{e.code}: #{e.message}" end ``` The [errors reference](https://docs.rocketverifier.com/errors) lists every API error code. ## Retries and timeouts - **Rate limits (429):** retried up to `max_retries` times, waiting for the `Retry-After` seconds, or 60 seconds when the header is missing. See [rate limits](https://docs.rocketverifier.com/rate-limits). - **Timeouts and network errors:** retried with 1, 2 and 3 second waits. - **Other errors:** raised straight away. - **Idempotency:** every POST, PUT and PATCH sends an `Idempotency-Key` reused across retries of that call. ## Next steps - [Reading results](https://docs.rocketverifier.com/results) Every status and sub_status, what it costs and what to do with it. - [All SDKs](https://docs.rocketverifier.com/sdks) Compare the Node.js, Python, Go, PHP and Ruby libraries and the CLI. ## Frequently asked questions ### Does the gem have runtime dependencies? No. It uses net/http, json and openssl from the standard library and supports Ruby 2.6 and later. ### Is the client thread safe? Yes for OAuth refresh: a mutex makes concurrent threads share one refresh. Each request opens its own Net::HTTP connection. ### Which errors does the gem retry? Rate limits (429), timeouts and network errors, up to `max_retries` times (3 by default). Other 4xx and 5xx responses raise straight away. --- # RocketVerifier CLI Source: https://docs.rocketverifier.com/sdks/cli > Run npx @rocketverifier/cli verify followed by an address, or install it globally with npm install -g @rocketverifier/cli. Authenticate with --api-key, ROCKETVERIFIER_API_KEY or rocketverifier config set-key. Every command prints readable text or, with --json, the raw API response, and exits non-zero on any error. `@rocketverifier/cli` brings the RocketVerifier API to your terminal. Verify one address, run a bulk job from a list or a file with a free list health preview, follow its progress, download the results and check your balance, all without writing code. It is built for scripts and CI pipelines: plain text for people, `--json` for machines and a non-zero exit code on every error. ## Install the CLI Run it on demand with `npx`, or install it globally for the `rocketverifier` command. CLI: ```bash npx @rocketverifier/cli verify deliverable@sandbox.rocketverifier.com # no install npm install -g @rocketverifier/cli # then: rocketverifier ... rocketverifier --version ``` ## Authenticate The CLI needs an API key. It reads the key from the first of these that is set. 1. The `-k, --api-key ` flag on the command. 2. The `ROCKETVERIFIER_API_KEY` environment variable. 3. The key saved with `rocketverifier config set-key`, in `~/.rocketverifier/config.json`. CLI: ```bash rocketverifier config set-key rv_live_your_key_here rocketverifier verify maya@northwind.io export ROCKETVERIFIER_API_KEY="rv_live_your_key_here" rocketverifier credits rocketverifier verify maya@northwind.io --api-key rv_test_your_sandbox_key ``` Live keys start with `rv_live_`; sandbox keys start with `rv_test_` and accept only [sandbox addresses](https://docs.rocketverifier.com/sandbox). Without a key, every command prints an error and exits with code 1. See [authentication](https://docs.rocketverifier.com/authentication) for creating keys. ### Set the API base URL The base URL defaults to `https://api.rocketverifier.com`. Override it in the same order: the `-u, --base-url ` flag, then `ROCKETVERIFIER_BASE_URL`, then the saved config. CLI: ```bash rocketverifier config set-base-url https://api.rocketverifier.com ROCKETVERIFIER_BASE_URL=https://api.rocketverifier.com rocketverifier credits rocketverifier credits --base-url https://api.rocketverifier.com rocketverifier config show # resolved key (redacted), base URL and config file path ``` ## Global options These options work with every command. Put them before or after the command. | Option | What it does | | --- | --- | | `-k, --api-key ` | API key for this run. Overrides the environment variable and the saved key. | | `-u, --base-url ` | API base URL for this run. | | `--json` | Print the raw API JSON instead of formatted text. | | `-v, --version` | Print the CLI version. | | `-h, --help` | Help for the CLI or for any command. | ## Verify an email `rocketverifier verify ` checks one address in real time with [`POST /v1/verify`](https://docs.rocketverifier.com/api/verify). CLI: ```bash rocketverifier verify deliverable@sandbox.rocketverifier.com ``` The text output starts with the address and its status, followed by labelled lines for `sub-status`, `reason`, `score`, `disposable`, `free`, `accept-all`, `catch-all`, `role`, `provider`, `did you mean` and `verified at` whenever the API returns them. Add `--json` for the full result, where flags such as `domain.disposable` are the strings `"yes"` and `"no"`. CLI: ```bash rocketverifier verify maya@northwind.io --json | jq -r '.status' rocketverifier verify maya@northwind.io --json | jq -r '.domain.disposable' # "yes" or "no" ``` The [reading results guide](https://docs.rocketverifier.com/results) explains every status and `sub_status`. ## Run a bulk job `rocketverifier bulk create` starts a job of up to 100,000 unique addresses from arguments, a file, or both. See the [batch API](https://docs.rocketverifier.com/api/batch). CLI: ```bash rocketverifier bulk create maya@northwind.io deliverable@sandbox.rocketverifier.com --name "Launch list" rocketverifier bulk create --file leads.csv --name "Q3 leads" rocketverifier bulk create --file leads.csv --wait ``` | Option | What it does | | --- | --- | | `-f, --file ` | A text or CSV file. The CLI splits it on new lines and commas and keeps every value containing `@`. | | `-n, --name ` | Job name. | | `-w, --wait` | Poll every 3 seconds until the job ends (up to 30 minutes). With `--json`, prints every result once the job completes. | The CLI counts unique addresses before sending and stops with `too_many_emails` above 100,000. Without `--wait`, it prints the job ID and the credits reserved. ### Check status and progress CLI: ```bash rocketverifier bulk status job_abc123 # status, processed/total and counts rocketverifier jobs progress job_abc123 # counts by status, rate per minute and ETA ``` ### Read and download results `bulk results` prints one page of results as a table; `bulk download` writes the full results file. CLI: ```bash rocketverifier bulk results job_abc123 --classification valid --limit 1000 --page 2 rocketverifier bulk download job_abc123 --output results.csv rocketverifier bulk download job_abc123 --filter send_safe --output safe.csv rocketverifier bulk download job_abc123 --include-original --output joined.csv rocketverifier bulk download job_abc123 --format json > results.json ``` | Command | Options | | --- | --- | | `bulk results ` | `-p, --page ` (default 1), `-l, --limit ` (default 100, up to 1000), `-c, --classification ` (`valid`, `invalid`, `risky`, `catch_all`, `disposable` or `unknown`) | | `bulk download ` | `-o, --output ` (default stdout), `--format ` (default `csv`), `--filter ` (`deliverable`, `undeliverable`, `risky`, `unknown` or `send_safe`), `--include-original` | `send_safe` keeps deliverable plus high-scoring catch-all addresses. `--include-original` joins upload jobs with your file's own columns, followed by the `rv_` result columns. ## Upload a file with a free preview `rocketverifier bulk upload ` creates a job from a CSV, TSV, TXT or XLSX file of up to 50 MB, or from a public `https://` URL. With `--preview`, the job stops with a free list health estimate and starts only when you confirm it. See [bulk upload](https://docs.rocketverifier.com/api/bulk-upload). CLI: ```bash rocketverifier bulk upload contacts.xlsx --email-column "Work Email" --preview --wait rocketverifier bulk confirm job_abc123 rocketverifier jobs progress job_abc123 rocketverifier bulk upload https://northwind.io/exports/leads.csv --name "Leads" ``` | Option | What it does | | --- | --- | | `-n, --name ` | Job name. | | `-e, --email-column ` | Header name or 0-based index of the email column. | | `--column-mapping ` | A JSON object such as `'{"email":"Work Email"}'`. Overrides `--email-column`. | | `--preview` | Stop for a free list health preview. Start the job with `bulk confirm`. | | `--callback-url ` | HTTPS URL that receives a signed POST when the job finishes. The callback secret is printed once. | | `-w, --wait` | Wait for the preview with `--preview`, or for the job to finish without it. | The preview shows the estimated bounce rate, the share of undeliverable, risky and unknown addresses, the credits needed and a confidence level. CLI: ```bash rocketverifier bulk preview job_abc123 --wait # wait until the preview is ready rocketverifier bulk preview job_abc123 --refresh # recompute it rocketverifier bulk confirm job_abc123 # charge and start; never charged twice ``` ## Manage jobs CLI: ```bash rocketverifier jobs list --status completed --limit 50 rocketverifier jobs cancel job_abc123 ``` - `jobs list` takes `-p, --page ` (default 1), `-l, --limit ` (default 20, up to 100) and `-s, --status `: `ingesting`, `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed` or `cancelled`. - `jobs cancel ` cancels a pending or running job and prints the credits refunded for unprocessed addresses. - `jobs progress ` shows live counts, throughput and ETA. ## Check credits CLI: ```bash rocketverifier credits rocketverifier credits --json | jq '.credits' ``` ## Command reference | Command | What it does | | --- | --- | | `verify ` | Verify one address in real time. | | `bulk create [emails...]` | Create a bulk job from arguments or `--file`. | | `bulk upload ` | Create a job from a file or an `https://` URL. | | `bulk preview ` | Show the free preview of an upload created with `--preview`. | | `bulk confirm ` | Charge and start a previewed job. | | `bulk status ` | Show a job's status and counts. | | `bulk results ` | Print one page of results. | | `bulk download ` | Download the full results as CSV or JSON. | | `jobs list` | List recent jobs. | | `jobs progress ` | Show counts, rate and ETA. | | `jobs cancel ` | Cancel a job and refund unprocessed addresses. | | `credits` | Show your credit balance. | | `config set-key ` | Save your API key. | | `config set-base-url ` | Save an API base URL. | | `config show` | Print the resolved configuration with the key redacted. | ## Output formats The CLI prints readable text by default and the raw API response with `--json`. - **Text:** tables and labelled lines, colored when stdout is a terminal. Set `NO_COLOR` to turn colors off. - **JSON:** `--json` prints the API response as indented JSON on stdout, with the API's snake_case field names. API errors print `{"error": {"code", "message", "details"}}` on stdout instead of text. - **Streams:** results go to stdout; spinners, progress lines and errors go to stderr, so piping stays clean. - **Downloads:** `bulk download` writes the file body exactly as the API returns it, to `--output` or stdout. ## Exit codes The exit code tells you whether the command worked, so a pipeline stops on any failure. | Code | When | | --- | --- | | `0` | The command succeeded, whatever the verification verdict. | | `1` | Any error: no API key, an invalid option value, an API error (for example `insufficient_credits` or `rate_limited`), a timeout or a network failure. | To fail a pipeline on the verdict itself, test the JSON with `jq -e`, which exits non-zero when the expression is false. CLI: ```bash rocketverifier verify "$EMAIL" --json | jq -e '.status == "deliverable"' > /dev/null ``` ## Retries and timeouts The CLI retries a 429 response up to 2 times when the API sends a `Retry-After` header, waiting for that many seconds (at most 30). Requests time out after 30 seconds; file uploads and downloads get 5 minutes. Every POST carries an `Idempotency-Key` reused across retries, so a retried call never charges twice. See [rate limits](https://docs.rocketverifier.com/rate-limits). ## Use the CLI in CI Use a sandbox key in CI so tests run for free and never touch real addresses. Store the key as a secret and expose it as `ROCKETVERIFIER_API_KEY`. GitHub Actions: ```yaml name: Email verification smoke test on: [push] jobs: verify: runs-on: ubuntu-latest steps: - uses: actions/setup-node@v4 with: node-version: 20 - name: Verify a sandbox address env: ROCKETVERIFIER_API_KEY: ${{ secrets.ROCKETVERIFIER_TEST_KEY }} run: | npx @rocketverifier/cli verify deliverable@sandbox.rocketverifier.com --json \ | jq -e '.status == "deliverable"' npx @rocketverifier/cli verify undeliverable@sandbox.rocketverifier.com --json \ | jq -e '.status == "undeliverable"' ``` For a nightly list clean, upload the export, wait for it and keep only safe addresses. CLI: ```bash JOB=$(rocketverifier bulk upload export.csv --wait --json | jq -r '.job_id') rocketverifier bulk download "$JOB" --filter send_safe --output clean.csv ``` ## Next steps - [Sandbox and testing](https://docs.rocketverifier.com/sandbox) All 8 sandbox addresses and their fixed results. - [All SDKs](https://docs.rocketverifier.com/sdks) Libraries for Node.js, Python, Go, PHP and Ruby. ## Frequently asked questions ### Does an undeliverable result fail the command? No. The exit code reports whether the call succeeded, not the verdict. Gate a pipeline on the result with `--json` and `jq -e`, for example `jq -e '.status == "deliverable"'`. ### Which API key wins when several are set? `--api-key` first, then the `ROCKETVERIFIER_API_KEY` environment variable, then the key saved with `config set-key`. ### Can I run the CLI in CI without spending credits? Yes. Use a sandbox key (`rv_test_`) and sandbox addresses such as `deliverable@sandbox.rocketverifier.com`. They return fixed results for free. ### Where does the CLI store my key? In `~/.rocketverifier/config.json`, created with file mode 600 inside a directory with mode 700. --- # Integrations Source: https://docs.rocketverifier.com/integrations > RocketVerifier connects four ways. Automation apps (Zapier, Make, n8n, Google Sheets, Chrome) call the API for you, website plugins and RocketShield block bad addresses on your forms, native connectors verify the contacts already in your CRM or email tool and write the result back, and bounce feeds from your sending platform keep your suppression list current and refund bounces automatically. Pick the integration by where the addresses live. Each one runs on the same engine and the same credits as the [API](https://docs.rocketverifier.com/api), so results match everywhere. ## Automate with no-code apps Automation apps call the API for you. Use them to verify addresses as they arrive in another tool, start bulk jobs and react when a job finishes. - [Zapier](https://docs.rocketverifier.com/integrations/zapier) Verify an email, run a batch, and trigger Zaps when a job completes or credits run low. - [Make](https://docs.rocketverifier.com/integrations/make) Modules for single and bulk verification, plus an instant trigger for completed jobs. - [n8n](https://docs.rocketverifier.com/integrations/n8n) A community node and a signed webhook trigger for every RocketVerifier event. - [Google Sheets](https://docs.rocketverifier.com/integrations/google-sheets) Formulas, one-click column verification, clean-up tools and hourly automation. - [Chrome extension](https://docs.rocketverifier.com/integrations/chrome-extension) Right-click any address, or scan the page you are on. ## Block bad addresses on your website and forms RocketShield checks the email field as the visitor types and stops the form when the address is undeliverable, disposable or breaks your rules. Platform plugins add server-side checks on top. - [RocketShield widget](https://docs.rocketverifier.com/integrations/widget) Two lines of HTML protect every email field on any site. - [WordPress](https://docs.rocketverifier.com/integrations/wordpress) Contact Form 7, Gravity Forms, WPForms, Ninja Forms and WooCommerce. - [Shopify](https://docs.rocketverifier.com/integrations/shopify) A theme app embed for storefront forms and a customer sync with tags and metafields. - [BigCommerce](https://docs.rocketverifier.com/integrations/bigcommerce) A Script Manager snippet for checkout and account pages, plus a customer sync. - [Magento](https://docs.rocketverifier.com/integrations/magento) Server-side checks at registration, guest checkout and newsletter signup. - [Webflow](https://docs.rocketverifier.com/integrations/webflow) RocketShield on site forms, and every submission verified server-side. - [Typeform](https://docs.rocketverifier.com/integrations/typeform) Every response verified as it arrives, delivered as a signed webhook. - [Jotform](https://docs.rocketverifier.com/integrations/jotform) Every submission verified, with the status written back into the form. ## Verify the contacts already in your tools Native connectors read contacts from the platform, verify them as one job and write the result back. Connect them from [Dashboard, Integrations](https://app.rocketverifier.com/dashboard/integrations). Every connector page lists what it reads, the field names it writes and the actions it can take. All connectors share these features: - **Scheduled syncs:** manual, daily, weekly or monthly, in full or incremental mode. Contacts verified recently are skipped and never charged twice. - **Write-back:** status, sub-status, score, verified-at and a `send`, `review` or `remove` recommendation, as fields, properties or tags. - **Actions by result:** tag, move, pause, unsubscribe or delete contacts per result type, with preview, undo and a CSV backup of every run. Catch-all and unknown contacts are never unsubscribed or deleted. - **Auto-verify new contacts** on platforms that send webhooks, at 1 credit per new contact. ### CRM - [HubSpot](https://docs.rocketverifier.com/integrations/hubspot) Contact properties, lists and new-contact verification. - [Salesforce](https://docs.rocketverifier.com/integrations/salesforce) Leads and Contacts, list views and campaigns. - [Zoho CRM](https://docs.rocketverifier.com/integrations/zoho_crm) Leads and Contacts in every data center. - [Pipedrive](https://docs.rocketverifier.com/integrations/pipedrive) People and saved filters. - [Microsoft Dynamics 365](https://docs.rocketverifier.com/integrations/dynamics365) Contacts, Leads, views and marketing lists. - [GoHighLevel](https://docs.rocketverifier.com/integrations/gohighlevel) Sub-account contacts, tags and email DND. - [monday.com](https://docs.rocketverifier.com/integrations/monday) Any board's email column, with result columns. ### Email marketing - [Mailchimp](https://docs.rocketverifier.com/integrations/mailchimp) Audience tags and automatic unsubscribe. - [ActiveCampaign](https://docs.rocketverifier.com/integrations/activecampaign) Custom fields, tags and list unsubscribe. - [Klaviyo](https://docs.rocketverifier.com/integrations/klaviyo) Profile properties, suppression and new sign-ups. - [Brevo](https://docs.rocketverifier.com/integrations/brevo) Contact attributes and blocklisting. - [MailerLite](https://docs.rocketverifier.com/integrations/mailerlite) Custom fields, groups and unsubscribe. - [Kit](https://docs.rocketverifier.com/integrations/kit) Custom fields, tags and unsubscribe. - [Constant Contact](https://docs.rocketverifier.com/integrations/constant_contact) Custom fields, tags and unsubscribe. - [GetResponse](https://docs.rocketverifier.com/integrations/getresponse) Hidden custom fields and tags. - [Drip](https://docs.rocketverifier.com/integrations/drip) Custom fields, tags and unsubscribe. ### Cold outreach Cold outreach connectors add the **Campaign safety net**: every hour, leads newly added to your campaigns are verified, and invalid and disposable leads are paused or blocked before the first email goes out. - [Smartlead](https://docs.rocketverifier.com/integrations/smartlead) Campaign leads, pause and unsubscribe. - [Instantly](https://docs.rocketverifier.com/integrations/instantly) Campaign leads and the workspace block list. - [lemlist](https://docs.rocketverifier.com/integrations/lemlist) Lead variables, pause and unsubscribe. - [Apollo.io](https://docs.rocketverifier.com/integrations/apollo) Contacts, lists and sequences. - [Reply.io](https://docs.rocketverifier.com/integrations/replyio) Contacts, campaigns, pause and opt-out. - [Woodpecker](https://docs.rocketverifier.com/integrations/woodpecker) Prospects, snippets, pause and blacklist. - [Outreach](https://docs.rocketverifier.com/integrations/outreach) Prospects, sequences and new prospects. ### Ecommerce, forms and databases - [Shopify](https://docs.rocketverifier.com/integrations/shopify) Customers, tags and metafields. - [BigCommerce](https://docs.rocketverifier.com/integrations/bigcommerce) Customers and customer attributes. - [Airtable](https://docs.rocketverifier.com/integrations/airtable) Any table's email column, with result columns. - [Typeform](https://docs.rocketverifier.com/integrations/typeform) Every response, verified as it arrives. - [Jotform](https://docs.rocketverifier.com/integrations/jotform) Every submission, with optional write-back. - [Webflow](https://docs.rocketverifier.com/integrations/webflow) Every form submission, server-side. ## Feed bounces back from your sending platform Bounce feeds import hard bounces, soft bounces and spam complaints from your sending platform into your suppression list in real time over a webhook, and RocketVerifier also polls SendGrid, Mailgun and Postmark once a day. With SendGrid, Mailgun or Postmark connected, every hard bounce of an address a job marked deliverable is refunded automatically. See the [bounce guarantee](https://docs.rocketverifier.com/integrations/bounce-guarantee). - [SendGrid](https://docs.rocketverifier.com/integrations/sendgrid) Signed Event Webhook, daily polling and Marketing Campaigns contacts. - [Mailgun](https://docs.rocketverifier.com/integrations/mailgun) Signed webhooks, daily polling and mailing lists. - [Postmark](https://docs.rocketverifier.com/integrations/postmark) Bounce and spam complaint webhooks, plus daily polling. - [Amazon SES](https://docs.rocketverifier.com/integrations/ses) Bounce and complaint notifications through SNS. ## Build your own Anything with an HTTP client can use RocketVerifier directly. - [API reference](https://docs.rocketverifier.com/api) Single and bulk verification, jobs, credits and webhooks. - [SDKs](https://docs.rocketverifier.com/sdks/nodejs) Typed clients with retries and webhook helpers. - [Webhooks](https://docs.rocketverifier.com/api/webhooks) Signed events for jobs, credits, monitors and integration syncs. - [RocketVerifier Connect](https://docs.rocketverifier.com/oauth) Build an app that other RocketVerifier users sign in to with OAuth. ## Frequently asked questions ### Do integrations cost extra? No. Every integration uses the same credits as the API, 1 credit per verified address, and `unknown` results are free. There is no per-integration fee. ### Which integration should I use to block fake signups? Use RocketShield on any website, or the WordPress, Shopify, BigCommerce, Webflow or Magento integration for those platforms. For forms you do not host, such as Typeform or Jotform, use the native connector, which verifies each submission as it arrives. ### Can I verify the contacts already in my CRM? Yes. Connect the CRM or email tool from Dashboard, Integrations. A sync reads the contacts, verifies them as one job and writes status, sub-status, score, verified-at and a send, review or remove recommendation back onto each contact. ### What if my tool is not listed? Use Zapier, Make or n8n to connect it, or call the API directly. Partners can also build their own app with RocketVerifier Connect. --- # Verify emails in Zapier Source: https://docs.rocketverifier.com/integrations/zapier > Add the RocketVerifier app in Zapier and connect it with an API key. Use Verify Email to check one address in any Zap, Verify Email Batch to submit up to 100,000 addresses, and the Job Completed and Credits Low triggers to react to your account. Each verification uses 1 credit and unknown results are free. The RocketVerifier app for Zapier verifies addresses inside any Zap and starts Zaps from your RocketVerifier account. It has two triggers, four actions and one search. ## Connect your account **Step 1. Create an API key** Open [API keys](https://app.rocketverifier.com/dashboard/api-keys) in the dashboard and create a key. A live key (`rv_live_`) verifies any address. A sandbox key (`rv_test_`) only accepts `@sandbox.rocketverifier.com` addresses and is free, which makes it ideal while you build the Zap. **Step 2. Add RocketVerifier to a Zap** In Zapier, add a step, search for [RocketVerifier](https://zapier.com/apps/rocketverifier) and choose an event. When Zapier asks for an account, paste the API key. **Step 3. Test the connection** Zapier tests the key with `GET /v1/credits` and labels the connection with the key's last four characters. A revoked key marks the connection as expired, and Zapier asks you to reconnect. ## Verify an email in a Zap **Verify Email** checks one address in real time. Map the email field from the previous step, such as a form answer or a new CRM contact. - `Email Address` (string, required): The address to verify. - `Timeout (seconds)` (integer): Optional, 5 to 60. Caps how long the API spends on the address. See [`timeout`](https://docs.rocketverifier.com/api/verify#request) for how the API applies it. | Output field | Type | What it holds | | --- | --- | --- | | `email` | string | The address as verified. | | `status` | string | `deliverable`, `undeliverable`, `risky` or `unknown`. | | `recommendation` | string | `send`, `review` or `remove`. | | `sub_status` | string | The reason behind the status, such as `mailbox_not_found` or `possible_typo`. See [sub-status values](https://docs.rocketverifier.com/results). | | `reason` | string | The legacy reason code, such as `accepted_email`. | | `score` | integer | Confidence from 0 to 100. | | `is_valid`, `is_invalid`, `is_risky`, `is_unknown` | boolean | One flag per status. | | `is_disposable`, `is_free_provider`, `is_catch_all`, `is_role`, `is_disabled`, `is_full_mailbox`, `is_toxic` | boolean | Address and domain flags. | | `accept_all` | string | The raw catch-all flag: `yes`, `no` or `unknown`. | | `catch_all_verdict` | string | `send_safe`, `send_with_caution` or `avoid` on catch-all domains, empty otherwise. | | `did_you_mean` | string | A corrected address when the input looks like a typo. | | `provider`, `domain_name` | string | The mailbox provider and the domain. | | `verified_at` | datetime | When the result was produced. | ## Verify a list in one step **Verify Email Batch** submits a list as one bulk job and returns right away. Use it when a Zap collects many addresses at once, such as a spreadsheet export. - **Email Addresses** (required): addresses separated by commas, semicolons or new lines, up to 100,000. Entries without an `@` are dropped before the job is created. - **Job Name** (optional): a name to find the job later. Defaults to `Zapier Batch `. The output has `job_id`, `total_emails`, `estimated_time_seconds`, `credits_used`, `credits_remaining`, `status` and `message`. Read the results with the **Job Completed** trigger or the **Get Job Results** action. Bulk pricing is the same as single checks: duplicates are counted once and `unknown` results are refunded. See [bulk verification](https://docs.rocketverifier.com/api/batch). ## Read the results of a job **Get Job Results** returns a job's status, counts and up to 1,000 result rows. - **Job ID** (required): pick a recent job from the dropdown, or map `job_id` from Verify Email Batch or Job Completed. - **Filter by Classification** (optional): `valid`, `invalid`, `risky`, `catch_all`, `disposable` or `unknown`. Each row in `results` has `email`, `status` (the classification), `recommendation`, `is_valid`, `is_invalid`, `is_risky`, `is_catch_all`, `is_disposable`, `score`, `sub_status` and `verified_at`. The job fields are the same as the Job Completed trigger below, plus `results_count` and `has_more_results`. ## Check your credit balance **Check Credits** returns `credits` (available), `used_today`, `used_this_month` and `timestamp`. Put it before a large batch to stop the Zap when the balance is too low. ## Find a job **Find Verification Job** is the app's search. It looks a job up by **Job ID** or by exact **Job Name** (case insensitive, newest first, across your 500 most recent jobs), with an optional **Status** filter: `pending`, `processing`, `completed`, `failed` or `cancelled`. It returns the job fields below, or nothing when no job matches. ## Start a Zap when a job completes **Job Completed** fires the moment a bulk job finishes. Turning the Zap on creates a RocketVerifier webhook for `job.completed`, and turning it off deletes it. | Output field | What it holds | | --- | --- | | `job_id`, `job_name`, `status` | The job. | | `total_emails`, `processed_emails` | Addresses in the job and addresses processed. | | `valid_count`, `invalid_count`, `risky_count`, `catch_all_count`, `disposable_count`, `unknown_count` | Results by classification. | | `progress_percent`, `is_completed` | 100 and true for a completed job. | | `download_url` | The CSV export of every result. | | `created_at`, `completed_at` | Timestamps. | The `unknown_count` is empty in the live trigger because the `job.completed` event does not carry it. Use Get Job Results when you need it. ## Start a Zap when credits run low **Credits Low** fires on the `credits.low` event (a charge left the balance at 100 credits or fewer) and on `credits.depleted` (the balance reached zero). Set **Only When Below** to fire only under a lower number; depleted alerts always fire. The output has `event`, `credits_remaining`, `threshold`, `is_depleted`, `timestamp` and `message`. Both triggers check the `X-RocketVerifier-Signature` header against the webhook secret when it is present, and stop on a mismatch. See [webhook signatures](https://docs.rocketverifier.com/api/webhooks). ## Example Zaps - **Form to CRM, clean addresses only:** form submission, then Verify Email, then a Filter on `recommendation` equals `send`, then create the CRM contact. - **Flag typos:** Verify Email, then Paths on `sub_status` equals `possible_typo`, then email the person with `did_you_mean`. - **Nightly list clean:** Schedule, then a spreadsheet lookup, then Verify Email Batch. A second Zap starts on Job Completed and sends `download_url` to Slack. - **Top-up reminder:** Credits Low, then a Slack or email alert to the account owner. ## Frequently asked questions ### Which field should my Zap filter on? Use `recommendation`. It is `send`, `review` or `remove`, so one Filter or Paths step covers every case. Use `status` and `sub_status` when you need the detail. ### Are the yes and no fields booleans in Zapier? Yes. The app converts the API's `"yes"` and `"no"` strings into real booleans such as `is_disposable` and `is_role`. The raw tri-state `accept_all` (`yes`, `no` or `unknown`) is also returned. ### How do I get every result of a large batch? Get Job Results returns up to 1,000 rows per call and sets `has_more_results` when there are more. For larger jobs, use the `download_url` from the Job Completed trigger to fetch the full CSV. ### Why did my Zap stop with an expired connection? The API key was revoked or deleted. Create a new key in the dashboard and reconnect the RocketVerifier account in Zapier. --- # Verify emails in Make Source: https://docs.rocketverifier.com/integrations/make > Add a RocketVerifier module to a Make scenario and connect it with an API key. Verify an Email Address checks one address with a send, review or remove recommendation, Create a Bulk Verification Job submits up to 100,000 addresses, and Watch Completed Jobs starts a scenario the moment a job finishes. The RocketVerifier app for Make has seven modules and one instant trigger. Modules are grouped as Email verification, Bulk jobs, Account and Other in the scenario editor. ## Connect your account **Step 1. Create an API key** Open [API keys](https://app.rocketverifier.com/dashboard/api-keys) and create a key. Use a sandbox key (`rv_test_`) with `@sandbox.rocketverifier.com` addresses while you build the scenario; it never spends credits. **Step 2. Create the connection** Add any RocketVerifier module to a scenario, click **Add** next to Connection and paste the key. Make tests it with `GET /v1/credits` and shows your balance on the connection. A key restricted to scopes needs `credits:read` for the connection test, `verify:single` for Verify an Email Address, `verify:bulk` for bulk jobs, `jobs:read` for the job modules and `webhooks:manage` for Watch Completed Jobs. See [authentication](https://docs.rocketverifier.com/authentication). ## Verify an email address **Verify an Email Address** runs a real-time check on one address. | Input | Required | Notes | | --- | --- | --- | | Email address | Yes | The address to verify. | | Timeout (seconds) | No | Caps how long the API spends on the address. See [`timeout`](https://docs.rocketverifier.com/api/verify#request). | | Idempotency key | No | Repeats with the same key return the stored result without charging again. | The output turns the API's `"yes"` and `"no"` strings into booleans, so filters work without string comparisons: | Output | What it holds | | --- | --- | | `status` | `deliverable`, `undeliverable`, `risky` or `unknown`. | | `recommendation` | `send`, `review` or `remove`. Filter on this. | | `sub_status`, `reason` | The reason behind the status. See [sub-status values](https://docs.rocketverifier.com/results). | | `score` | Confidence from 0 to 100. | | `is_deliverable`, `is_undeliverable`, `is_risky`, `is_unknown` | One flag per status. | | `is_disposable`, `is_free`, `is_catch_all`, `is_role`, `is_disabled`, `is_full_mailbox`, `is_spam_trap` | Address and domain flags as booleans. | | `catch_all_verdict` | `send_safe`, `send_with_caution` or `avoid` on catch-all domains. | | `did_you_mean`, `provider` | Typo suggestion and mailbox provider. | | `deliverability_tier`, `authentication_score`, `toxic`, `abuse`, `spam_trap` | Extra signals from the API. | | `domain`, `account`, `dns`, `activity`, `evidence` | The raw API objects. | | `verified_at` | When the result was produced. | ## Verify a list as a bulk job **Create a Bulk Verification Job** submits 1 to 100,000 addresses for asynchronous verification. Inputs are **Email addresses** (an array), an optional **Job name** and an optional **Idempotency key**. The output has `job_id`, `total_emails`, `estimated_time_seconds`, `credits_to_use` and `credits_remaining`. Then use one of these: - **Get a Job** returns `status`, `progress_percent`, `total_emails`, `processed_emails`, the counts by classification (`valid_count`, `invalid_count`, `risky_count`, `catch_all_count`, `disposable_count`, `unknown_count`) and the `created_at`, `started_at` and `completed_at` timestamps. Pick the job from the dropdown or map its ID. - **List Job Results** is a search module that outputs one bundle per email: `email`, `classification`, `recommendation`, `is_valid`, `is_disposable`, `is_catch_all`, `confidence_score`, `sub_status` and `verified_at`, plus `job_id` and `job_status`. Filter by **Classification**, cap the bundles with **Limit** (default 1,000) and skip ahead with **Start page**. It pages through the results 1,000 at a time. - **List Jobs** returns your bulk jobs newest first, optionally filtered by **Status**, up to **Limit** (default 20). Each bundle has the job fields above plus `credits_used` and `download_url`. ## Check your credit balance **Get Credits** returns `credits`, `used_today` and `used_this_month`. Add it before a large job, with a filter that stops the scenario when the balance is too low. ## Start a scenario when a job completes **Watch Completed Jobs** is an instant trigger. Creating its webhook in Make registers a RocketVerifier webhook named "Make: Watch Completed Jobs" for `job.completed`, and deleting it in Make removes it from RocketVerifier. Each bundle has `event`, `event_id`, `timestamp` and `data`, which holds `job_id`, `status`, `name`, `total_emails`, `processed_emails`, the counts by classification, `created_at`, `completed_at` and `download_url`. Only `job.completed` events start the scenario; the webhook acknowledges and drops any other event, such as the test event. ## Call any endpoint **Make an API Call** sends an authorized request to any path under `https://api.rocketverifier.com`, for example `/v1/credits`. Use it for endpoints the modules do not cover, such as [webhooks](https://docs.rocketverifier.com/api/webhooks) or the [credits](https://docs.rocketverifier.com/api/credits) history. ## Example scenarios - **Clean leads before the CRM:** a form or CRM trigger, then Verify an Email Address, then a filter on `recommendation` = `send`, then create the contact. - **Weekly list clean:** a schedule, then read a sheet, then Create a Bulk Verification Job. A second scenario starts with Watch Completed Jobs and sends `download_url` to your team. - **Route by result:** Verify an Email Address, then a router with one route per `recommendation` value. ## Frequently asked questions ### How do I verify a comma-separated list in Make? Create a Bulk Verification Job takes an array. Map a text value with `split(text; ",")` to turn it into one. ### Does a retried scenario charge twice? Not when you set an Idempotency key. Verify an Email Address and Create a Bulk Verification Job both accept one, and a repeat with the same key returns the stored result instead of charging again. ### Why does Watch Completed Jobs not verify the signature? Make custom app webhooks only see the parsed body, never the raw bytes the signature covers. The protection is the secret, unguessable Make webhook URL, so keep it private and recreate the webhook if it leaks. --- # Verify emails in n8n Source: https://docs.rocketverifier.com/integrations/n8n > Install the n8n-nodes-rocketverifier community node, add a RocketVerifier API credential, and use the RocketVerifier node to verify emails, run bulk jobs and check credits. The RocketVerifier Trigger starts a workflow on any RocketVerifier event and rejects every delivery whose signature does not match. The `n8n-nodes-rocketverifier` package adds two nodes that share one credential: **RocketVerifier**, an action node, and **RocketVerifier Trigger**, which starts workflows from RocketVerifier events. ## Install the node In n8n open **Settings, Community Nodes, Install** and enter the package name: ```text n8n-nodes-rocketverifier ``` On self-hosted n8n you can also install it from the command line and restart n8n: ```bash cd ~/.n8n/nodes npm install n8n-nodes-rocketverifier ``` ## Add the credential Create a **RocketVerifier API** credential: | Field | Value | | --- | --- | | API Key | A key from [API keys](https://app.rocketverifier.com/dashboard/api-keys). Use an `rv_test_` sandbox key with `@sandbox.rocketverifier.com` addresses to build without spending credits. | | Base URL | `https://api.rocketverifier.com`. Leave it as is. | n8n tests the credential with `GET /v1/credits`. A key restricted to scopes needs `verify:single` for Verify, `verify:bulk` for Create, `jobs:read` for status, progress, results, lists and downloads, `jobs:write` for Delete, and `webhooks:manage` for the trigger. ## Verify an email **Email, Verify** checks one address in real time and outputs the full [verification result](https://docs.rocketverifier.com/api/verify#response): `status`, `sub_status`, `score`, `catch_all_verdict`, `did_you_mean`, `verified_at` and every evidence field. Options: - **Convert Yes/No Fields to Booleans:** turns `domain.acceptAll`, `domain.disposable`, `domain.free`, `account.role`, `account.disabled`, `account.fullMailbox`, `toxic`, `abuse` and `spam_trap` from `"yes"` and `"no"` into `true` and `false`. `"unknown"` stays as is. Off by default. - **Idempotency Key:** sent as the `Idempotency-Key` header, so a retried item is never charged twice. - **Timeout (Seconds):** 5 to 60. See [`timeout`](https://docs.rocketverifier.com/api/verify#request) for how the API applies it. ## Run bulk jobs The **Batch Job** resource covers the full job lifecycle. | Operation | What it does | | --- | --- | | **Create** | Submits up to 100,000 addresses (comma, semicolon or newline separated, or an expression that returns an array) with an optional **Job Name** and **Idempotency Key**. | | **Get Status** | Returns a job's status and summary counts. | | **Get Progress** | A poll-friendly view from `GET /v1/jobs/{id}/progress`: `processed`, `remaining`, `percent`, `counts`, `counts_by_status`, `rate_per_minute` and `eta_seconds`. | | **Get Results** | Per-email results with `sub_status` and `verified_at`, optionally filtered by classification. Use **Page** and **Limit** (up to 1,000 per page) or **Return All**. Turn on **Split Into Items** for one item per email. | | **Get Many** | Lists your jobs, optionally filtered by status (`awaiting_confirmation`, `ingesting`, `pending`, `processing`, `completed`, `failed`, `cancelled`). Up to 100 per page, or **Return All**. One item per job by default. | | **Download Results** | Exports a completed job as a **CSV File (Binary)**, ready for Google Drive, S3 or email, or as **JSON** (`job_id` and `results`). A job that is still running returns `job_not_complete`. | | **Delete** | Cancels the job and refunds credits for every address still waiting to be processed. | The **Credit, Check** operation returns your balance and the credits used today and this month. ## Start a workflow from RocketVerifier events **RocketVerifier Trigger** registers a webhook when the workflow is activated (or when you click **Listen for test event**) and deletes it when the workflow is deactivated. Changing the events or the n8n URL recreates it. | Event | Fires when | | --- | --- | | `job.completed` | A bulk job finished. `data` has `job_id`, the counts and `download_url`. | | `job.failed` | A bulk job failed. `data.error` says why. | | `credits.low` | A charge left the balance at 100 credits or fewer. | | `credits.depleted` | The balance reached zero. | | `email.verified` | A single verification finished. | | `monitor.alert` | A list health or domain authentication monitor raised an alert. | The output is the full envelope `{ event, event_id, timestamp, data }`. Turn on **Only Output Data** to get `data` alone, and set **Webhook Name** to change the name shown in RocketVerifier (default `n8n: `). ### How deliveries are verified Every delivery is checked before the workflow runs, and anything that fails gets HTTP 401: - The `X-RocketVerifier-Signature` header (`t=,v1=`) is computed over the raw request bytes with the secret returned when the webhook was created. Several `v1` entries are accepted during secret rotation. - The timestamp must be within 300 seconds of the n8n server clock. Change it under **Options, Signature Tolerance**, and keep the server clock in sync. - Comparison is constant time. See [webhook signatures](https://docs.rocketverifier.com/api/webhooks) for the scheme. ## Example workflows - **Sheet row to verified row:** Google Sheets trigger, then Verify, then update the row with `status` and `score`. - **Clean form leads:** Typeform trigger, then Verify, then an IF node on `status` equal to `deliverable` before adding the lead to your CRM. - **Scheduled list clean:** Schedule, then Create. A second workflow starts on `job.completed`, runs Download Results as CSV and uploads the file to Google Drive. - **Low balance alert:** `credits.low`, then a Slack message. ## Frequently asked questions ### Why does my IF node treat "no" as true? The API returns flags such as `domain.disposable` as the strings `"yes"`, `"no"` or `"unknown"`, and a non-empty string is truthy. Turn on Convert Yes/No Fields to Booleans, or compare explicitly with `$json.domain.disposable === "yes"`. ### Does the trigger work on self-hosted n8n? Yes, as long as n8n is reachable over public HTTPS. RocketVerifier only delivers webhooks to https URLs. Set `WEBHOOK_URL` when n8n runs behind a proxy or tunnel. ### What happens if I rotate the webhook secret? The trigger keeps the secret it received when the webhook was created. Deactivate and reactivate the workflow so it registers a fresh webhook and secret. --- # Verify emails in Google Sheets Source: https://docs.rocketverifier.com/integrations/google-sheets > Install the RocketVerifier add-on, save your API key under Extensions, RocketVerifier, Settings, then select a column and choose Verify selected column. Five result columns appear next to it, with a send, review or remove recommendation. The RV_VERIFY formula checks single cells, and automation verifies new rows every hour. The RocketVerifier add-on verifies addresses where your list already lives. It works from a menu, from formulas and on a schedule, and writes results the moment they are ready. ## Install the add-on and save your key **Step 1. Install** In a spreadsheet, open **Extensions, Add-ons, Get add-ons**, search for RocketVerifier and install it. The add-on asks for access to the open spreadsheet only, to call `api.rocketverifier.com`, to show its sidebar, and to run its hourly trigger. **Step 2. Save your API key** Open **Extensions, RocketVerifier, Settings (API key)** and paste a key from [API keys](https://app.rocketverifier.com/dashboard/api-keys). The sidebar checks it with `GET /v1/credits` and shows a masked version afterwards. The key lives in your Google account's add-on properties, never in the sheet. ## Verify a column Select a column of addresses (a whole column such as `A:A` works) and choose **Extensions, RocketVerifier, Verify selected column**. The add-on writes five columns to the right of the selection: | Column | What it holds | | --- | --- | | **RV Status** | `deliverable`, `undeliverable`, `risky` or `unknown`. | | **RV Sub-status** | The reason, such as `mailbox_not_found` or `catch_all`. See [sub-status values](https://docs.rocketverifier.com/results). | | **RV Score** | Confidence from 0 to 100. | | **RV Recommendation** | `send`, `review` or `remove`: valid is send; invalid and disposable are remove; risky, catch-all and unknown are review. | | **RV Verified at** | The API's `verified_at`, as a real date cell. | When the first selected cell is not an email it is treated as a header row, and the result headers are written next to it. If the target columns already hold data, the sidebar asks before overwriting. How the column runs: - **Cached addresses** are written immediately and cost nothing. - **50 or fewer** remaining addresses are verified in real time, 10 at a time. - **More than 50** run as one bulk job. The sidebar shows progress every few seconds and writes results as soon as the job completes. Results are matched by address, so sorting the sheet during a job is safe. - **More than 50,000 rows** run as a series of 50,000-row segments, one bulk job each. Closing the sidebar never loses a job: the hourly trigger keeps writing results, and reopening the sidebar resumes polling. **Cancel job** stops it and refunds every address still waiting to be processed. ## Use formulas | Formula | Returns | | --- | --- | | `=RV_VERIFY(A2)` | The status. Pass a range of up to 100 addresses to get a matching range. | | `=RV_VERIFY_DETAILS(A2)` | One row: status, sub-status, score and `did_you_mean`. Pass a single column of up to 100 addresses for one row each. | Blank cells return an empty value, and cells that are not shaped like an address return `invalid_input` without calling the API. Use Verify selected column for lists longer than 100. ## Clean up the results **Extensions, RocketVerifier, Clean up & automate** works on the result columns of the active sheet. - **Colour rows:** remove rows red, review rows yellow and send rows green, including rows added later. Your own colours and rules are untouched, and Remove colours deletes only these three rules. - **Show only bad, only review or all:** filters the sheet on RV Recommendation. - **Move bad rows to RV Removed** or **Delete bad rows**, optionally including review rows. The add-on shows the count first, then copies every affected row (values and formulas) to a hidden **RV Backup** sheet. - **Undo last clean-up** puts the rows back at their original row numbers. The last 5 clean-ups can be undone in turn. ## Verify new rows automatically Save automation in the same sidebar to have one hourly trigger keep the column current: - **Verify new rows automatically:** rows with an address and no result are verified. - **Re-verify on a schedule:** daily, weekly or monthly, rows whose result is older than its freshness window are verified again. Defaults are 7 days for unknown, 30 for risky and catch-all, 90 for valid and 180 for invalid and disposable. Change them per spreadsheet from 0 to 730 days. - An address that already has a fresh result in another row is copied from there for free. Google runs add-on triggers at most once an hour, so automation works hourly; keep the sidebar open for minute-by-minute progress on a large run. The sidebar shows the last run and any error, such as a missing key or an empty balance. Turning automation off deletes the trigger. ## Credits - 1 credit per verified address, the same as the [API](https://docs.rocketverifier.com/api/verify#credits). `unknown` results are free. - Results are cached for 6 hours per user, so repeats within that window are free. - Bulk jobs charge each unique address once. See [bulk verification](https://docs.rocketverifier.com/api/batch). ## Frequently asked questions ### Does recalculating a formula charge again? No. Every result is cached for 6 hours per user, so recalculation, copied formulas and repeat runs within that window are free. Unknown results are cached for 15 minutes and are never charged. ### Who pays for formulas in a shared sheet? The person whose key evaluates them. Each collaborator who wants formulas to calculate installs the add-on and saves their own key, which is stored in their Google account and never in the spreadsheet. ### How large a sheet can I verify? Any size. Columns over 50 addresses run as bulk jobs of up to 100,000 addresses, and columns over 50,000 rows are split into segments that run one after another, even with the sidebar closed. ### Can I undo a clean-up? Yes. Every move or delete is backed up to a hidden RV Backup sheet first. Undo last clean-up puts the rows back at their original row numbers, and the last 5 clean-ups can be undone in turn. --- # Verify emails in Chrome Source: https://docs.rocketverifier.com/integrations/chrome-extension > Install RocketVerifier Email Verifier for Chrome and sign in with your RocketVerifier account. Right-click any address to verify it, type one into the popup, or scan the current page to verify every address on it at once, then filter, copy or download the results. Each verification uses 1 credit from your account. The RocketVerifier extension brings verification to any page in Chrome: prospect lists, company contact pages, CRMs and inboxes. ## Install and sign in **Step 1. Install** Add **RocketVerifier: Email Verifier** to Chrome from the Chrome Web Store and pin it to the toolbar. **Step 2. Sign in** Open the popup and sign in with your RocketVerifier account. Chrome opens the RocketVerifier consent screen, which asks for `verify:single`, `verify:bulk`, `jobs:read` and `account:read`. No API key is stored in the browser. ## Verify an address - **Right-click:** select an address on any page, or right-click a `mailto:` link, and choose **Verify with RocketVerifier**. The popup opens with the result, and the toolbar badge shows it at a glance: ✓ deliverable, ✕ undeliverable, ! risky, ? unknown. - **Popup:** type or paste any address. Each result shows the status, the 0 to 100 score, the [sub-status](https://docs.rocketverifier.com/results), the [catch-all verdict](https://docs.rocketverifier.com/catch-all) on catch-all domains and a typo suggestion when the address looks mistyped. ## Scan a page Click **Scan page** in the popup to find every address on the current tab, in the visible text and in `mailto:` links, up to 500 per scan. Scans of 10 or fewer addresses are verified in real time; larger scans run as one [bulk job](https://docs.rocketverifier.com/api/batch) that continues after the popup closes. When the scan finishes, filter the list by status, copy the deliverable addresses, or download everything as a CSV. ## Credits Every verification uses 1 credit from the signed-in account, the same as the dashboard and the API, and `unknown` results are free. The popup shows your balance with a **Buy credits** link. ## Permissions | Permission | Why | | --- | --- | | `contextMenus` | The **Verify with RocketVerifier** menu item. | | `activeTab`, `scripting` | Read the current tab's text, only when you click Scan page or use the menu. | | `identity` | Sign in with RocketVerifier Connect. | | `storage` | Keep your sign-in, the last result and scan progress. | | `api.rocketverifier.com`, `app.rocketverifier.com` | The API and the sign-in server, nothing else. | ## Frequently asked questions ### Does the extension read every page I visit? No. It reads a page only when you click Scan page or use the right-click menu, and it sends only the email addresses it finds. It has no content scripts and no access to your browsing history. ### Do I need to paste an API key? No. You sign in with RocketVerifier Connect (OAuth with PKCE), and verifications run on the signed-in account's credits. ### What happens to a large page scan if I close the popup? Scans of more than 10 addresses run as one bulk job, which keeps running after the popup closes. Reopen the popup to see the results. --- # Block bad emails on any form with RocketShield Source: https://docs.rocketverifier.com/integrations/widget > Create a shield in the dashboard, add your site's domains to it, and paste two script tags before the closing body tag. RocketShield checks every email field as the visitor types, blocks undeliverable, disposable and toxic addresses by default, and stops the form until the address passes. Each check costs 1 credit and unknown results are free. RocketShield is a small script that verifies email fields in real time. It finds every `input[type="email"]` on the page, including fields added later by single-page apps, shows the result under the field, and stops the form while the address is blocked. ## Install RocketShield **Step 1. Create a shield** Open [RocketShield](https://app.rocketverifier.com/dashboard/rocketshield) in the dashboard and create a shield. Give it a name, add every domain the form runs on under **Allowed domains**, and choose the blocking rules and message. **Step 2. Copy the key** The dashboard shows the shield key (`rs_...`) and the embed code when the shield is created. Copy it then: afterwards the dashboard shows only the key's prefix. **Rotate key** issues a new one at any time. **Step 3. Paste the snippet** Paste the embed code before the closing `` tag of every page with a form, or in your site builder's footer code: HTML: ```html ``` **Step 4. Test it** Type a sandbox address into the form, such as `disposable@sandbox.rocketverifier.com` or `undeliverable@sandbox.rocketverifier.com`. Sandbox addresses return fixed results for free on every shield. Platform guides wrap the same snippet: [Shopify](https://docs.rocketverifier.com/integrations/shopify), [BigCommerce](https://docs.rocketverifier.com/integrations/bigcommerce), [Webflow](https://docs.rocketverifier.com/integrations/webflow) and [WordPress](https://docs.rocketverifier.com/integrations/wordpress). ## What gets blocked and what gets a warning Every result lands in one of three states. A blocked address shows the shield's message in red and stops the form; a warning shows in amber and lets the form submit; a pass shows in green. | Result | Default | Shield rule | | --- | --- | --- | | Broken syntax | Blocked | Always on. Checked in the browser, no credit used. | | `undeliverable`, including DNS errors and an unavailable mailbox server | Blocked | Always on. | | Disposable address | Blocked | **Block disposable**, on by default. | | Toxic address (offensive words, placeholders and keyboard mashes in the local part) | Blocked | **Block toxic**, on by default. | | Free provider, such as gmail.com | Pass | **Block free domain**, off by default. Turn it on for B2B forms. | | Role address, such as info@ or sales@ | Warning (`risky`) | **Block role-based**, off by default. | | Catch-all domain | Warning (`risky`) | **Block catch all**, off by default. | | `unknown` | Pass | **Block unknown**, off by default. | | Any other `risky` result | Warning | None. | | `deliverable` | Pass | None. | The blocked message is the shield's message; the dashboard fills in "Valid business email is required." for new shields. ## Options Rules, message and behaviour are set on the shield in the dashboard, so you change them without touching the site. The script loads them from the shield every time a page opens. | Shield setting | Default | What it does | | --- | --- | --- | | Allowed domains | Required | Hostnames the key works on. `example.com` also covers its subdomains, and `*.example.com` covers subdomains explicitly. A request from any other site is refused. | | Blocking rules | See the table above | Which results stop the form. | | Blocked message | "Valid business email is required." | Shown under the field and as the browser's validation message. | | Prevent form submit | On | Stops the form while an email field is blocked. Off shows the message without stopping the form. | | Field selector | Empty | A CSS selector for the fields to check. Empty checks every `input[type="email"]`. | | Rate limit | 25 | Checks per page view per hour, 1 to 100. See below. | | Hide "Powered by RocketVerifier" | Off | Removes the badge under the field. | | Debug mode | Off | Logs the loaded settings and each result to the browser console. | The script waits 500 ms after the last keystroke before it checks, and checks again when the field loses focus. ### Make rules stricter for one site `rocketShieldConfig` accepts overrides that can only tighten the shield's rules, which is useful when one shield serves several sites: HTML: ```html ``` | Option | Effect | | --- | --- | | `apikey` | Required. The shield key. | | `blockDisposable`, `blockRoleBased`, `blockFreeProvider`, `blockCatchAll`, `blockUnknown`, `blockToxic` | `true` turns the rule on for this page. `false` has no effect, so a page can never loosen the shield. | | `blockedMessage` | Replaces the message on this page, up to 200 characters. | ### Check extra fields Add `data-rocketshield` to any input to check it too, for example a text field that holds an email: HTML: ```html ``` ## React to results in your own code RocketShield fires two events on the input, and both bubble up to the form: JavaScript: ```js document.addEventListener("rocketshield:verified", (event) => { const { email, result } = event.detail; console.log(email, result.status, result.score); }); document.addEventListener("rocketshield:blocked", (event) => { analytics.track("signup_email_blocked", { reason: event.detail.result.reason }); }); ``` `result` has `email`, `status`, `reason`, `score`, `provider`, `domain` (`name`, `acceptAll`, `disposable`, `free`) and the booleans `is_disposable`, `is_free_provider`, `is_catch_all`, `is_role_based` and `is_toxic`. The script also exposes `window.RocketShield`: | Method | What it does | | --- | --- | | `verify(email)` | Checks an address and returns the result. Cached per page. | | `isValid(email)` | `true` when a checked address passes the rules. | | `getResult(email)` | The cached result, or `null`. | | `clearCache()` | Forgets cached results. | | `init()` | Scans the page for new fields. | | `getConfig()` | The settings loaded from the shield. | | `version` | The script version. | ## Rate limit The rate limit caps how many addresses one page view checks: 25 per hour by default, set from 1 to 100 on the shield. The count lives in the page, counts only real checks (cached results and syntax errors are free), and starts again an hour after the page opened. When a page reaches the limit, further addresses are not checked and the form submits normally. Shield requests are not throttled by IP on the server; the allowed domains and this per-page limit are what protect your credits. Pair RocketShield with a CAPTCHA or your own server-side throttle on forms that attract bots. ## Pricing - **1 credit** for every `deliverable`, `undeliverable` and `risky` result, the same as the [API](https://docs.rocketverifier.com/api/verify#credits). - **Free:** `unknown` results, addresses on your own suppression list, sandbox addresses, syntax errors and repeat checks of the same address in a page. - When the balance is below 1 credit, checks stop and forms submit normally until you [buy credits](https://app.rocketverifier.com/dashboard/buy-credits). The dashboard shows each shield's checks, blocked and allowed counts. ## Troubleshooting - **Nothing happens:** open the console with debug mode on. A missing `apikey` logs a warning and the script does nothing. - **Checks fail on one site:** the site's hostname is not in **Allowed domains**. Add the exact domain, including staging hosts such as `store.myshopify.com` or `site.webflow.io`. - **A field is not checked:** it is not `type="email"`. Add `data-rocketshield`, or set a field selector on the shield. - **Server-side check needed too:** see [verify at signup](https://docs.rocketverifier.com/guides/signup-verification). ## Frequently asked questions ### Is the shield key a secret? No. The `rs_` key is public by design and only works from the domains listed on the shield. Never put a secret `rv_live_` API key in a web page. ### What happens if the API is unreachable or my credits run out? The form keeps working. RocketShield clears its message and lets the visitor submit, so an outage never blocks real signups. Keep a server-side check for addresses that must be verified. ### Does retyping the same address cost again? No. Results are cached in the page, so the same address is checked once per page view. ### Can a visitor bypass RocketShield? A visitor who turns off JavaScript skips any browser check. For signups that matter, verify again on your server with the API or use a platform plugin that checks on submit, such as WordPress or Magento. --- # Verify emails on WordPress forms and WooCommerce Source: https://docs.rocketverifier.com/integrations/wordpress > Install the RocketVerifier plugin, paste your API key under Settings, RocketVerifier, and every supported form checks the email as the visitor types and again on the server when the form is submitted. Undeliverable and disposable addresses are rejected, and one cached result covers both checks, so each address uses a single credit. The RocketVerifier plugin protects every form on a WordPress site. Each supported form plugin gets a server-side check on submit, so a blocked address never gets through, even with JavaScript turned off. ## Install the plugin **Step 1. Install and activate** In WordPress admin open **Plugins, Add New**, search for **RocketVerifier**, then click **Install Now** and **Activate**. To install by hand, upload the `rocketverifier` folder to `/wp-content/plugins/` and activate it on the Plugins screen. **Step 2. Paste your API key** Open **Settings, RocketVerifier**, paste a key from [API keys](https://app.rocketverifier.com/dashboard/api-keys) and click **Save Settings**. The page shows **Connected** and your credit balance. **Step 3. Choose what to block** Pick the validation options and form integrations below. Protection starts with the next submission. ## Choose what to block | Setting | Default | What it does | | --- | --- | --- | | Block invalid emails | On | Rejects `undeliverable` addresses: mailboxes that do not exist, domains that cannot receive mail and broken syntax. | | Block disposable emails | On | Rejects temporary and throwaway addresses. | | Enable real-time validation | On | Checks the address as the visitor types and shows the result under the field. | | Block submissions when the verification service is unavailable | Off | Rejects submissions when the API cannot be reached, returns an error or your credits run out. Leave it off so forms keep working. | `deliverable`, `risky` and `unknown` addresses are accepted. When the API flags a typo, the message suggests the corrected address, for example "Did you mean name@gmail.com?". ## Supported forms Each integration turns on when its form plugin is active and has its own switch under **Form Integrations**. | Form | Server-side check | | --- | --- | | Contact Form 7 | Required and optional email fields. | | Gravity Forms | Email fields. | | WPForms | Email fields. | | Ninja Forms | Email fields. | | WooCommerce checkout | The billing email, on the classic and the block checkout. | | WooCommerce My Account registration | The registration email. | | Any other HTML form | Live check only: add `data-rv-email` to the input. | HTML: ```html ``` The live check runs on every `type="email"` input, every input with `data-rv-email`, and the email fields of Contact Form 7 and Gravity Forms. ## Credits and caching - 1 credit per verified address. `unknown` results are free. - Results are cached for 10 minutes per address, so the live check and the submission count once. Failed and `unknown` results are not cached. - The public live-check endpoint allows 10 checks per visitor per 60 seconds, which keeps bots from spending your credits. ## Customize with filters Developers can tune the plugin with WordPress filters: | Filter | Default | Use it to | | --- | --- | --- | | `rocketverifier_rate_limit` | `10` | Change live checks per visitor per window. Return `0` to turn the limit off. | | `rocketverifier_rate_limit_window` | `60` | Change the window in seconds. | | `rocketverifier_client_ip` | `REMOTE_ADDR` | Supply the visitor IP behind a proxy or CDN. | | `rocketverifier_cache_ttl` | `600` | Change the cache lifetime in seconds. Return `0` to turn caching off. | | `rocketverifier_request_timeout` | `30` | Change the HTTP timeout for API calls in seconds. | | `rocketverifier_block_reason` | | Return `''` to allow a result, or a reason code to block it. Receives the API response. | | `rocketverifier_validation_message` | | Rewrite the message shown to the visitor. | | `rocketverifier_ninja_forms_is_email_field` | | Treat other Ninja Forms field types as email fields. | PHP: ```php // Also block role addresses such as info@ and sales@. add_filter('rocketverifier_block_reason', function ($reason, $verification) { if ($reason === '' && ($verification['account']['role'] ?? '') === 'yes') { return 'invalid'; } return $reason; }, 10, 2); ``` The API returns flags such as `account.role` as the strings `"yes"`, `"no"` or `"unknown"`, so compare them explicitly. See the [verification result](https://docs.rocketverifier.com/api/verify#response). ## Frequently asked questions ### What happens if the API cannot be reached? Submissions go through without verification, so your forms and checkout keep working during an outage or when credits run out. Turn on Block submissions when the verification service is unavailable to reject them instead. ### Does the live check and the submit check cost two credits? No. Each result is cached for 10 minutes per address, so checking while the visitor types and again on submit uses one credit. Unknown results are free and are never cached. ### Is my API key exposed to visitors? No. The browser talks to your own WordPress site through admin-ajax, and only the server calls the RocketVerifier API with the key. ### Can I verify a custom form? Add `data-rv-email` to its email input for the live check. Server-side checks run for the supported form plugins and WooCommerce. --- # Verify Shopify customers and storefront forms Source: https://docs.rocketverifier.com/integrations/shopify > Connect Shopify from Dashboard, Integrations, Shopify to install the RocketVerifier app. Turn on the RocketShield app embed in the theme editor to check account, newsletter and contact forms as shoppers type, and use the customer sync to verify every customer, tag it rv: and keep new and updated customers verified automatically. RocketVerifier for Shopify has two parts that work together: **RocketShield** stops bad addresses on storefront forms before they are submitted, and the **customer sync** verifies every customer record, including those created at checkout. ## Install the app In RocketVerifier open [Dashboard, Integrations, Shopify](https://app.rocketverifier.com/dashboard/integrations/shopify), enter your `.myshopify.com` domain and click **Connect**. Shopify asks you to approve `read_customers` and `write_customers`, then sends you back to the dashboard. The same install adds the RocketShield app embed to your theme editor. ## Check storefront forms with RocketShield **Step 1. Create a shield** Open [RocketShield](https://app.rocketverifier.com/dashboard/rocketshield), create a shield and add your store's domains to **Allowed domains**: the custom domain and `your-store.myshopify.com`. Choose the blocking rules and message, then copy the `rs_` key. **Step 2. Turn on the app embed** In Shopify open **Online Store, Themes, Customize, App embeds** and turn on **RocketShield**. Paste the shield key and pick where it runs: - **All pages** (default), which includes the footer newsletter form. - **Account and contact pages only**: register, login, account, account activation, password reset and the contact page. Save the theme. **Step 3. Test it** Open the storefront and type `disposable@sandbox.rocketverifier.com` into the newsletter form. The form shows the shield's message and stops the submission. The embed loads `https://app.rocketverifier.com/widget/v2.js` with `defer`, and loads nothing until a key is set. Blocking rules, the message and the rate limit come from the shield in the dashboard; the checkboxes in the app embed do not change them. The [RocketShield guide](https://docs.rocketverifier.com/integrations/widget) covers every rule and option. ## Sync customers with the native connector The customer sync verifies the customers already in your store and every new one, then writes the result onto the customer record so you can segment, filter and automate on it in Shopify. ### Connect Shopify **Step 1** In RocketVerifier open **Dashboard → Integrations → Shopify**, enter your `.myshopify.com` domain and click **Connect** to install the app and approve `read_customers` and `write_customers`. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ### What it syncs **Sources.** All customers. **Incremental syncs.** Customers updated since the last sync. ### Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ### Write-back **Status fields.** - `rocketverifier.email_status (metafield)` - `rocketverifier.email_recommendation (metafield)` - `rocketverifier.email_verified_at (metafield)` Customer metafields in the `rocketverifier` namespace, written 20 customers per request. **Status tags.** `rv:`, e.g. `rv:undeliverable`; the other `rv:` status tags are removed. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). ### Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ### Auto-verify new contacts Turn on **Auto-verify new contacts**. RocketVerifier subscribes the store to `customers/create` and `customers/update`; each delivery is checked against Shopify's HMAC signature and de-duplicated on `X-Shopify-Webhook-Id`. An update whose address was already verified is ignored, so RocketVerifier's own tag and metafield writes never trigger a second check. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Use the results in Shopify - **Segments:** build a customer segment on the tag `rv:undeliverable` or `rv:risky` and exclude it from Shopify Email campaigns. - **Flows:** start a Shopify Flow when a customer is tagged `rv:undeliverable`, for example to notify your team. - **Metafields:** `rocketverifier.email_recommendation` holds `send`, `review` or `remove` for apps that read customer metafields. ## Privacy The app handles Shopify's mandatory privacy webhooks: `customers/data_request` is answered with what RocketVerifier holds for the customer, `customers/redact` deletes that customer's verification data, and `shop/redact` deletes everything for the store. Uninstalling the app disconnects the integration and deletes its access token. ## Frequently asked questions ### Does RocketShield run on the Shopify checkout? Theme app embeds run on theme pages, and the Shopify checkout and new customer account pages are not theme pages. Addresses entered there are verified by the customer sync as soon as the customer is created. ### Why do the blocking checkboxes in the app embed not change anything? Blocking rules and the message come from the shield in the RocketVerifier dashboard. Set them on the shield, and every page using that key follows them. ### Does tagging a customer trigger another verification? No. A customer update whose address was already verified is ignored, so RocketVerifier's own tags and metafields never cause a second charge. --- # Verify BigCommerce customers and checkout emails Source: https://docs.rocketverifier.com/integrations/bigcommerce > Paste the RocketShield snippet into Storefront, Script Manager to check checkout, account and contact forms as shoppers type. Connect a store API account from Dashboard, Integrations, BigCommerce to verify every customer, write the result into customer attributes and verify new customers as they are created. RocketVerifier for BigCommerce has two parts: a **RocketShield** snippet that checks forms on the storefront, and a **customer sync** that verifies every customer record. ## Add RocketShield with Script Manager **Step 1. Create a shield** Open [RocketShield](https://app.rocketverifier.com/dashboard/rocketshield) and create a shield. Add the store's domains to **Allowed domains**: the custom domain, `store-xxxx.mybigcommerce.com`, and the checkout domain if it is different. Choose the blocking rules and message, then copy the `rs_` key. **Step 2. Create the script** In BigCommerce open **Storefront, Script Manager, Create a Script** and set: | Field | Value | | --- | --- | | Name | `RocketShield` | | Placement | Footer | | Location | All pages (the snippet narrows this down itself, and this includes the checkout) | | Script category | Essential | | Script type | Script | **Step 3. Paste the snippet** Paste this into **Script contents** and replace the key: Script Manager: ```html ``` **Step 4. Test it** Save, then type `disposable@sandbox.rocketverifier.com` into the account creation form on the storefront. ### Choose which pages are protected Set `PAGES` at the top of the snippet: - `'forms'` (default): `/checkout`, `/embedded-checkout`, `/finishorder.php`, `/login.php` (login and account creation), `/account.php` and `/contact-us`. - `'all'`: every page, which also covers footer newsletter forms. Until the placeholder key is replaced, the snippet does nothing. ### Checkout Script Manager scripts run on the checkout with Optimized One-Page Checkout. The checkout is a React app, and RocketShield picks up its email field as soon as it appears, with live feedback under the field. Every customer created at checkout is also verified by the customer sync below. The [RocketShield guide](https://docs.rocketverifier.com/integrations/widget) covers every rule and option. ## Sync customers with the native connector The customer sync verifies the customers already in your store and every new one, and writes the result into customer attributes you can filter and export. ### Connect BigCommerce **Step 1** In BigCommerce create a store API account (**Settings → Store-level API accounts**) with the **Customers: modify** scope. **Step 2** In RocketVerifier open **Dashboard → Integrations → BigCommerce**, paste the credentials below (the access token and store hash) and click **Connect**. They are validated against the platform before anything is saved. **Step 3** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | The API account's access token. | | Store hash | Required | The `stores/` part of the API path shown with the API account. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ### What it syncs **Sources.** All customers or any customer group. **Incremental syncs.** Customers modified since the last sync. ### Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ### Write-back **Status fields.** - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Customer attributes, created on first use. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ### Auto-verify new contacts Turn on **Auto-verify new contacts**. RocketVerifier registers a `store/customer/created` webhook to `https://api.rocketverifier.com/webhooks/connectors/bigcommerce/{integration_id}`. BigCommerce does not sign webhooks, so a random token is sent in an `X-RV-Webhook-Token` header and checked on every delivery, and the customer is re-read from the API before it is verified. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Frequently asked questions ### Why must the script category be Essential? With BigCommerce's cookie consent banner on, Functional and Analytics scripts wait for the shopper's consent, which would leave your forms unprotected until they accept. Essential scripts load right away. Mention the script in your privacy policy. ### Does it work on a headless or Catalyst storefront? Headless storefronts do not use Script Manager. Add the two-line RocketShield embed to the storefront's layout instead, and the customer sync works the same way. ### Do I need a BigCommerce app? No. The snippet is pasted into Script Manager, and the customer sync connects with a store API account. --- # Verify emails in Magento and Adobe Commerce Source: https://docs.rocketverifier.com/integrations/magento > Install the RocketVerifier_EmailVerification module, enable it under Stores, Configuration, RocketVerifier, Email Verification, and paste your API key. Undeliverable and disposable addresses are rejected on the server at customer registration, guest checkout and newsletter signup, across the storefront, REST and GraphQL. The RocketVerifier module verifies email addresses inside Magento itself, so every storefront, headless frontend and API client gets the same protection. ## Install the module Install with Composer, then enable the module and its cache type: ```bash composer require rocketverifier/module-email-verification bin/magento module:enable RocketVerifier_EmailVerification bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:enable rocketverifier bin/magento cache:flush ``` To install by hand, copy the module to `app/code/RocketVerifier/EmailVerification/` and run the same `module:enable` and `setup:upgrade` steps. ## Configure it Open **Stores, Configuration, RocketVerifier, Email Verification**: | Field | Default | What it does | | --- | --- | --- | | Enabled | No | Turns verification on. | | API Key | | Your key from [API keys](https://app.rocketverifier.com/dashboard/api-keys). Stored encrypted, at default or website scope. | | Timeout (seconds) | 5 | 5 to 30. Sent to the API as `timeout`. | | Block Undeliverable Emails | Yes | Rejects `undeliverable` addresses. The message follows the `sub_status` and suggests `did_you_mean` when the API spots a typo. | | Block Disposable Emails | Yes | Rejects disposable addresses. Set it to No to accept them. | | Fail Open | Yes | Accepts the address when the API cannot be reached, times out or returns an error, including when credits run out. | | Customer Registration, Guest Checkout, Newsletter Subscription | Yes | Turns each check on or off. | `deliverable`, `risky` and `unknown` addresses are always accepted. You can also set the key from the command line: ```bash bin/magento config:sensitive:set rocketverifier/general/api_key rv_live_your_key_here ``` ## Where addresses are checked | Where | Areas | | --- | --- | | Customer registration | Storefront, REST (`POST /V1/customers`) and GraphQL (`createCustomerV2`). | | Guest checkout | The standard checkout, plus every guest order before payment is placed, including GraphQL `placeOrder` and express checkouts. | | Newsletter signup | The footer form, REST and GraphQL (`subscribeEmailToNewsletter`). | ## Credits and caching - 1 credit per verified address. `unknown` results are free. - Successful results are cached for 10 minutes in the **RocketVerifier Results** cache type (`rocketverifier`). Errors are never cached. - API errors are logged to `var/log/system.log`: errors for a bad key or an empty balance, warnings for timeouts. ## Test it Use a sandbox key (`rv_test_`) with `@sandbox.rocketverifier.com` addresses to test registration, guest checkout and the newsletter form for free. `undeliverable@sandbox.rocketverifier.com` is rejected and `deliverable@sandbox.rocketverifier.com` goes through. Every sandbox address is listed under [Try it](https://docs.rocketverifier.com/api/verify#try-it). ## Frequently asked questions ### Does a shopper who retries checkout pay twice? No. Results are cached for 10 minutes in a dedicated cache type, and a single request never calls the API twice, so a retried checkout or a registration that also subscribes to the newsletter uses one credit. ### What happens if the API is down or credits run out? With Fail Open on, which is the default, the address is accepted and the error is logged to `var/log/system.log`. Turn Fail Open off to show the shopper a please try again message instead. ### Are admin-created customers checked? Customers and orders created in the Magento admin are not checked. Customers created through the REST API, including by admin integrations, are. --- # Verify Webflow form emails Source: https://docs.rocketverifier.com/integrations/webflow > Paste the RocketShield embed into Site settings, Custom code, Footer code to check every Webflow form as visitors type. Connect Webflow from Dashboard, Integrations, Webflow to verify every form submission on the server, including submissions that skip the browser, and receive each result as an email.verified webhook. Webflow sites get two layers of protection: **RocketShield** stops bad addresses in the browser before a form is sent, and the **native connector** verifies every submission on the server, including bots that post directly. ## Add RocketShield to your site **Step 1. Create a shield** Open [RocketShield](https://app.rocketverifier.com/dashboard/rocketshield), create a shield and add `your-site.webflow.io` and your custom domains to **Allowed domains**. Choose the blocking rules and message, then copy the `rs_` key. **Step 2. Paste the embed** In Webflow open **Site settings, Custom code, Footer code** to protect every page, or **Page settings, Custom code, Before tag** for one page. Paste the embed and replace the key: Footer code: ```html ``` **Step 3. Publish and test** Publish the site and type `disposable@sandbox.rocketverifier.com` into a form on the published page. Webflow's **Email** form field renders as `input[type="email"]`, so standard Webflow forms work without changes. To check a plain text field, add the custom attribute `data-rocketshield` to it. The [RocketShield guide](https://docs.rocketverifier.com/integrations/widget) covers every rule and option. ## Verify every submission with the native connector The connector verifies each form submission on the server and delivers the result as a signed [`email.verified`](https://docs.rocketverifier.com/api/webhooks) webhook event, so you can act on it in any system. Subscribe a webhook endpoint to `email.verified` under [Dashboard, Webhooks](https://app.rocketverifier.com/dashboard/webhooks) to receive them. ### Connect Webflow **Step 1** In RocketVerifier open **Dashboard → Integrations → Webflow** and click **Connect**. You are sent to Webflow to approve access, then back to the dashboard. RocketVerifier asks for `sites:read`, `sites:write` (to create the webhook) and `forms:read`. Alternatively paste a Webflow site API token. **Step 2** Pick the forms to watch. RocketVerifier registers a `form_submission` webhook on the site. | Field | Required | Where to find it | | --- | --- | --- | | Site API token (instead of OAuth) | Optional | A site API token generated in the Webflow site settings. | Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ### What it syncs **Sources.** The forms of every site you authorize. **Incremental syncs.** Submissions since the last sync. ### Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ### Write-back Webflow submissions cannot be edited, so nothing is written back. Each result is sent as an `email.verified` webhook event with `data.source = "webflow"`. ### Auto-verify new contacts On by default for Webflow. Deliveries are signed (`x-webflow-signature`, HMAC-SHA256 of `timestamp:body`), and deliveries older than 5 minutes are rejected. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Frequently asked questions ### Why does RocketShield not run in the Designer? Webflow runs custom code only on the published site. Publish, then test on your `webflow.io` or custom domain. ### Can the result be written back to the Webflow submission? Webflow submissions cannot be edited. Each result is sent as an `email.verified` webhook event with `data.source` set to `webflow`, which you can route to your CRM, Zapier, Make or n8n. ### Do I need a paid Webflow plan? Custom code needs a paid site plan or a Workspace plan that includes it. The server-side connector works on any site with forms. --- # Verify Typeform responses Source: https://docs.rocketverifier.com/integrations/typeform > Connect Typeform from Dashboard, Integrations, Typeform and pick the forms to watch. RocketVerifier registers a signed webhook on each form, verifies the email in every completed response, and sends the result as an email.verified webhook event with data.source set to typeform. Existing responses can be verified in bulk with a sync. The Typeform connector verifies every respondent's email as soon as the response is submitted, with no change to the form. Typeform responses are read-only, so results come back to you as webhook events instead of being written into Typeform. ## Verify responses with the native connector ### Connect Typeform **Step 1** In RocketVerifier open **Dashboard → Integrations → Typeform** and click **Connect**. You are sent to Typeform to approve access, then back to the dashboard. RocketVerifier asks for `accounts:read`, `forms:read`, `responses:read`, `webhooks:read`, `webhooks:write` and `offline`. Alternatively paste a Typeform personal access token with the same access. **Step 2** Pick the forms to watch. RocketVerifier registers a signed webhook on each one. | Field | Required | Where to find it | | --- | --- | --- | | Personal access token (instead of OAuth) | Optional | Typeform → Account → Personal tokens. | Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ### What it syncs **Sources.** Any form (completed responses). **Incremental syncs.** Responses submitted since the last sync. ### Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ### Write-back Typeform responses cannot be edited, so nothing is written back. Each result is sent as an `email.verified` webhook event with `data.source = "typeform"`. ### Auto-verify new contacts On by default for Typeform: registering the webhook is the opt-in. Deliveries carry `Typeform-Signature: sha256=` with a per-integration secret and are checked against the raw body. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Receive results as webhook events Each verified response fires an `email.verified` event to every webhook endpoint subscribed to it. Create one under [Dashboard, Webhooks](https://app.rocketverifier.com/dashboard/webhooks), or use the [n8n trigger](https://docs.rocketverifier.com/integrations/n8n). The `data` object looks like this: email.verified data: ```json { "email": "maya@northwind.io", "status": "deliverable", "sub_status": "none", "score": 97, "classification": "valid", "disposable": "no", "accept_all": "no", "catch_all_verdict": null, "verified_at": "2026-11-11T09:42:17Z", "source": "typeform", "integration_id": "int_8f2c0d", "source_id": "a1B2c3D4", "contact_id": "x7k2m9p4q1", "job_id": "job_3b9e71" } ``` `source_id` is the form id and `contact_id` is the response token. See [webhooks](https://docs.rocketverifier.com/api/webhooks) for the envelope and signature. ## Frequently asked questions ### Can RocketShield check a Typeform while the respondent types? Typeform forms do not run third-party scripts, so verification happens the moment the response is submitted. Results arrive within seconds as an `email.verified` event. ### Which answer is verified? The field you set as the email field for the form (a field ref, id or hidden field name). Without one, the first email-type answer, then a hidden field named `email`. ### How do I act on a bad address? Subscribe a webhook endpoint, or a Zapier, Make or n8n workflow, to `email.verified` and filter on `data.source` equal to `typeform` and `status`. For example, add only `deliverable` respondents to your CRM. --- # Verify Jotform submissions Source: https://docs.rocketverifier.com/integrations/jotform > Connect Jotform from Dashboard, Integrations, Jotform with an API key and pick the forms to watch. RocketVerifier verifies the email in every new submission, can write the status into a hidden question on the form, and sends each result as an email.verified webhook event. Forms embedded with their source code can also use RocketShield for live checks. The Jotform connector verifies every submission's email on the server, so it works on every Jotform form however it is shared or embedded. ## Check forms live with RocketShield Live checks work when the form's HTML is part of your own page. Embed the form with Jotform's **Source code** option, then add the [RocketShield](https://docs.rocketverifier.com/integrations/widget) snippet and your site's domain to the shield's allowed domains. RocketShield then checks the email field as the visitor types. Forms shared as a jotform.com link or embedded as an iframe or script run on Jotform's domain, where your page's scripts cannot reach them. Those forms are covered by the connector below. ## Verify submissions with the native connector ### Connect Jotform **Step 1** In Jotform open **Settings → API → Create New Key** (Full Access if you want write-back, otherwise Read Access). **Step 2** In RocketVerifier open **Dashboard → Integrations → Jotform**, paste the credentials below (the key and your region) and click **Connect**. They are validated against the platform before anything is saved. **Step 3** Pick the forms to watch. RocketVerifier registers a webhook on each one. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Jotform → Settings → API. | | Region | Required | `us` (api.jotform.com), `eu` (eu-api.jotform.com) or `hipaa` (hipaa-api.jotform.com). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ### What it syncs **Sources.** Any form. **Incremental syncs.** Submissions created since the last sync. ### Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ### Write-back **Status fields.** - `The status question you choose (optional)` Add a Short Text question (for example "Email status", hidden) and set it as the form's status field in the integration settings; it is filled with deliverable / undeliverable / risky / unknown. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). ### Auto-verify new contacts On by default for Jotform. Jotform does not sign webhooks, so the registered URL carries a random per-integration token and the submission is re-read from the API by its id; the webhook body is never trusted. Each result is also sent as an `email.verified` event with `data.source = "jotform"`. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Receive results as webhook events Each verified submission fires an `email.verified` event with `data.source` set to `jotform`, `source_id` set to the form id and `contact_id` set to the submission id. Subscribe an endpoint under [Dashboard, Webhooks](https://app.rocketverifier.com/dashboard/webhooks), or connect Zapier, Make or n8n, to route each result. The payload is the same as the [Typeform example](https://docs.rocketverifier.com/integrations/typeform#receive-results-as-webhook-events). See [webhooks](https://docs.rocketverifier.com/api/webhooks) for the envelope and signature. ## Frequently asked questions ### How do I filter submissions by email status in Jotform? Add a hidden Short Text question such as Email status and set it as the form's status question in the integration settings. RocketVerifier fills it with `deliverable`, `undeliverable`, `risky` or `unknown`, so you can filter submissions and drive Jotform conditions on it. ### Which API key access do I need? Full Access to write the status back into submissions. Read Access is enough when you only want `email.verified` events. ### Why is the webhook body not trusted? Jotform does not sign webhooks. RocketVerifier checks a random per-integration token in the webhook URL, then reads the submission from the Jotform API by its id, so a forged request can never inject an address. --- # Verify HubSpot contacts Source: https://docs.rocketverifier.com/integrations/hubspot > Connect HubSpot from Dashboard, Integrations, HubSpot with OAuth. RocketVerifier verifies all contacts or any list, writes status, sub-status, score, verified-at and a Send, Review or Remove recommendation into contact properties, and verifies every new contact and changed email as it happens. Build HubSpot workflows and lists on the RV Email Recommendation property. The RocketVerifier app for HubSpot installs with OAuth and needs no setup inside HubSpot. The RV properties appear on every contact after the first sync, ready for lists, workflows and reports. ## Install the HubSpot app Open [Dashboard, Integrations, HubSpot](https://app.rocketverifier.com/dashboard/integrations/hubspot) and click **Connect**. HubSpot asks you to pick the account and approve these scopes: | Scope | Why | | --- | --- | | `crm.objects.contacts.read`, `crm.objects.contacts.write` | Read contacts and write the RV properties. | | `crm.schemas.contacts.read`, `crm.schemas.contacts.write` | Create the RocketVerifier property group and properties. | | `crm.lists.read`, `crm.lists.write` | Sync a list, and move contacts to a list as an action. | Then pick the source, schedule and write-back options in the integration settings and click **Sync now**. ## Sync contacts with the native connector ### Connect HubSpot **Step 1** In RocketVerifier open **Dashboard → Integrations → HubSpot** and click **Connect**. You are sent to HubSpot to approve access, then back to the dashboard. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ### What it syncs **Sources.** All contacts, or any contact list (static or active). **Incremental syncs.** Contacts whose `lastmodifieddate` is after the last sync. Reads are paged by contact id, so lists over 10,000 contacts are read completely. ### Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ### Write-back **Status fields.** - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Contact properties in a RocketVerifier property group (labels RV Email Status, RV Email Sub-status, RV Email Score, RV Verified At and RV Email Recommendation, a Send / Review / Remove dropdown). They are created automatically on the first write-back. Updates are sent 100 contacts at a time and every contact is accounted for individually. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ### Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Move to list**: Adds the contact to the list you pick (`moveToListId`). Undo removes it again. - **Delete**: Archives the contact. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ### Auto-verify new contacts Turn on **Auto-verify new contacts**. HubSpot sends `contact.creation` (and email `contact.propertyChange`) events to RocketVerifier's app webhook, signed with HubSpot's v3 signature; each new or changed email is verified (1 credit) and written back. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Use the results in HubSpot **RV Email Recommendation** is a dropdown property with the values Send, Review and Remove, so it works everywhere HubSpot filters on properties: - **Active lists:** a list where RV Email Recommendation is Remove becomes your suppression segment for marketing emails. - **Workflows:** enroll contacts when RV Email Recommendation is known, then branch on its value. For example, set Remove contacts to non-marketing, and send Review contacts to an owner for a manual check. - **Reports:** chart RV Email Status by source to see which forms and imports bring in bad addresses. - **Freshness:** filter on **RV Verified At** to find contacts verified more than 90 days ago and re-check them with a scheduled sync. To verify only a segment, build an active list in HubSpot and pick it as the sync source. Read the [CRM hygiene guide](https://docs.rocketverifier.com/guides/crm-hygiene) for a complete cleaning routine. ## Frequently asked questions ### Are lists over 10,000 contacts verified completely? Yes. Reads page through contacts by id, so lists and incremental syncs of any size are read in full. ### Does a contact edit trigger a new verification? Only a change to the email property does. Auto-verify listens for new contacts and email changes, and addresses verified recently are skipped and never charged twice. ### Can I keep my own property names? Yes. Map each value to an existing contact property in the integration settings, or clear a name to stop that property from being written. --- # Salesforce email verification Source: https://docs.rocketverifier.com/integrations/salesforce > Verify Salesforce Leads and Contacts and write the result into custom fields on both objects. ## Connect Salesforce **Step 1** In RocketVerifier open **Dashboard → Integrations → Salesforce** and click **Connect**. You are sent to Salesforce to approve access, then back to the dashboard. Sandboxes and My Domain logins are supported. **Step 2** Create the four custom fields below on **both Lead and Contact** before the first write-back. **Step 3** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** All Leads, All Contacts, all Leads and Contacts, any Lead or Contact list view, and active campaigns (their Lead and Contact members). **Incremental syncs.** Records with `LastModifiedDate` after the last sync. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `RV_Email_Status__c (Text 40)` - `RV_Email_Sub_Status__c (Text 80)` - `RV_Email_Score__c (Number 3,0)` - `RV_Verified_At__c (Date/Time)` Written 200 records at a time with per-record results. Missing fields are reported by name instead of failing the whole run; map other field names in the integration settings if you already have them. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Unsubscribe**: Sets the standard `HasOptedOutOfEmail` field to true. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Requirements and limits - The custom fields must exist on both Lead and Contact (create them in Setup → Object Manager). --- # Zoho CRM email verification Source: https://docs.rocketverifier.com/integrations/zoho_crm > Verify Zoho CRM Leads and Contacts in any data center and write the result into custom fields. ## Connect Zoho CRM **Step 1** In RocketVerifier open **Dashboard → Integrations → Zoho CRM** and click **Connect**. You are sent to Zoho CRM to approve access, then back to the dashboard. Every Zoho data center (US, EU, IN, AU, JP, CN, SA, UK, CA) is supported; the right one is detected during sign-in. **Step 2** Create the four custom fields below on Leads and Contacts. **Step 3** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** All Leads, All Contacts, both, or any Leads/Contacts custom view. **Incremental syncs.** Records modified since the last sync (`If-Modified-Since`). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `RV_Email_Status` - `RV_Email_Sub_Status` - `RV_Email_Score` - `RV_Verified_At` API names of single-line / number / date-time custom fields on Leads and Contacts. Missing fields are detected and reported explicitly. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Unsubscribe**: Sets the standard `Email_Opt_Out` field. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Requirements and limits - Create the custom fields on both Leads and Contacts before the first write-back. Records are written 100 at a time with a result for each record. --- # Pipedrive email verification Source: https://docs.rocketverifier.com/integrations/pipedrive > Verify Pipedrive people and write the result into custom person fields. ## Connect Pipedrive **Step 1** In RocketVerifier open **Dashboard → Integrations → Pipedrive** and click **Connect**. You are sent to Pipedrive to approve access, then back to the dashboard. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** All people, or any saved people filter. **Incremental syncs.** People updated since the last sync. The primary email of each person is verified. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `RV Email Status` - `RV Email Sub-status` - `RV Email Score` - `RV Verified At` - `RV Email Recommendation` Custom person fields, created automatically on first use. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Delete**: Deletes the person. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. --- # Microsoft Dynamics 365 email verification Source: https://docs.rocketverifier.com/integrations/dynamics365 > Verify Dynamics 365 (Dataverse) Contacts and Leads, write the result into columns on both tables and opt bad addresses out of email. ## Connect Microsoft Dynamics 365 **Step 1** In RocketVerifier open **Dashboard → Integrations → Microsoft Dynamics 365**, enter your environment URL (e.g. `https://contoso.crm4.dynamics.com`) and click **Connect**. You are sent to Microsoft to sign in with your work account and approve access to that environment, then back to the dashboard. **Step 2** Create the five columns below on **both Contact and Lead** before the first write-back. **Step 3** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** All active Contacts, all open Leads, both, any static marketing list of Contacts or Leads, and any system or personal view of Contacts or Leads. **Incremental syncs.** Records with `modifiedon` after the last sync. The email verified is `emailaddress1`. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `new_rv_emailstatus (Single line of text, 40)` - `new_rv_emailsubstatus (Single line of text, 80)` - `new_rv_emailscore (Whole number, 0 to 100)` - `new_rv_verifiedat (Date and time)` - `new_rv_emailrecommendation (Single line of text, 20)` Dataverse columns on Contact and Lead. `new_` is the default publisher prefix; set your own prefix (`fieldPrefix`) or map existing column logical names in the integration settings. Column metadata is checked before each write-back and missing columns are reported by name. Each record is updated individually. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Unsubscribe**: Sets `donotbulkemail` and `donotemail` to true (only `donotbulkemail` with `optOutBulkOnly`). The previous values are recorded, so Undo restores exactly what was there. - **Move to list**: Adds the record to the static marketing list you pick (`moveToListId`). Contacts go to Contact lists, Leads to Lead lists; dynamic and locked lists are skipped. - **Delete**: Deletes the Contact or Lead record. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Requirements and limits - Creating Dataverse columns needs System Customizer or admin rights and a solution publisher, so the columns are created by you, once, with your publisher prefix. RocketVerifier only reads and writes them. - Dynamic marketing lists are not offered as a source; sync the matching view instead. - New-contact webhooks are not offered for Dynamics 365. Scheduled incremental syncs pick up new and changed records. - Commercial and GCC environments (`.crm.dynamics.com`) are supported. GCC High and China cloud environments use other sign-in hosts and are not accepted. --- # GoHighLevel email verification Source: https://docs.rocketverifier.com/integrations/gohighlevel > Verify HighLevel sub-account contacts, write custom fields and status tags, set email DND on bad addresses and verify new contacts as they are created. ## Connect GoHighLevel **Step 1** In RocketVerifier open **Dashboard → Integrations → GoHighLevel** and click **Connect**. You are sent to GoHighLevel to approve access, then back to the dashboard. Pick the sub-account (location) to connect; agency-level installs are rejected. Alternatively paste a Private Integration Token and its location id. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | Private Integration Token (instead of OAuth) | Optional | A sub-account Private Integration Token with contacts read/write, locations read, custom fields read/write and tags read access. | | Location id | Optional | The id of the sub-account the token belongs to (the `` in `app.gohighlevel.com/v2/location//...`). Required with a token. | Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** All contacts, or contacts with a given tag (one source per location tag). **Incremental syncs.** Contacts whose `dateUpdated` is after the last sync. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `RV Email Status` - `RV Email Sub-status` - `RV Email Score` - `RV Verified At` - `RV Email Recommendation` Contact custom fields (keys `contact.rv_email_status` etc.), created automatically on first use; the score is a numeric field, the rest are text. ### Status tags `rv-status:` (prefix configurable), e.g. `rv-status:undeliverable`. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag (default `rv-invalid`). - **Unsubscribe**: Turns on email-channel DND with the message "RocketVerifier: email failed verification". Other channels keep their settings and contacts already on DND are left as they are; Undo clears DND only on contacts RocketVerifier changed. - **Delete**: Deletes the contact. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Auto-verify new contacts Turn on **Auto-verify new contacts**. The RocketVerifier marketplace app receives HighLevel's `ContactCreate` events, checks each delivery's `X-GHL-Signature` (Ed25519) against HighLevel's published public key (the legacy RSA `X-WH-Signature` is accepted when the Ed25519 header is absent), matches it to the integration by location id and de-duplicates it; each new email is verified and written back. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Requirements and limits - One integration covers one sub-account. Connect each sub-account separately. - Smart lists are not exposed by HighLevel's public API; use tags to sync a segment. - New-contact events come from the marketplace app, so auto-verify works with the OAuth connection. --- # monday.com email verification Source: https://docs.rocketverifier.com/integrations/monday > Verify the email column of any monday.com board, write the result into columns on the same board and verify new items as they are created. ## Connect monday.com **Step 1** In RocketVerifier open **Dashboard → Integrations → monday.com** and click **Connect**. You are sent to monday.com to approve access, then back to the dashboard. Alternatively paste a monday.com personal API token. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | Personal API token (instead of OAuth) | Optional | monday.com Developer Center → API token. New-item webhooks need the OAuth connection. | Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** Any board, or a single group of a board. The email column is the one you configure (column id or title), else the board's first Email column, else a column titled "Email". Email addresses inside text columns are read too. **Incremental syncs.** Items whose `updated_at` is after the last sync (filtered by RocketVerifier; monday has no "updated since" filter, so every page is read). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `RV Email Status` - `RV Email Sub-status` - `RV Email Score` - `RV Verified At` - `RV Email Recommendation` Board columns, found by id or title and created on the board on first write-back (Text columns, Numbers for the score). Written 25 items per request; a rejected item is isolated so the rest of the batch succeeds. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Move to list**: Moves the item to the group you pick (`moveToListId`: a group id, or `/` to limit it to one board). Undo moves it back to the group it was read from. - **Delete**: Archives the item (restorable from the board archive for 30 days), or deletes it when `deleteMode` is `delete`. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Auto-verify new contacts Turn on **Auto-verify new contacts**. RocketVerifier creates a `create_item` webhook on each synced board and answers monday's challenge request automatically. Each delivery carries a JWT signed with the RocketVerifier app's signing secret and is checked before the new item is re-read to get its email; sub-items are ignored. Webhooks require the OAuth connection (monday does not sign webhooks created with a personal token). Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Requirements and limits - Boards have no tags or unsubscribe state, so write-back is column-based and the remove actions are move to a group or archive. - monday's Basic and Standard plans allow 1,000 API calls per day. A sync that reaches the limit stops with a rate-limit error until it resets at midnight UTC. --- # Mailchimp email verification Source: https://docs.rocketverifier.com/integrations/mailchimp > Clean Mailchimp audiences: tag every member with its status and unsubscribe bad addresses automatically. ## Connect Mailchimp **Step 1** In RocketVerifier open **Dashboard → Integrations → Mailchimp** and click **Connect**. You are sent to Mailchimp to approve access, then back to the dashboard. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** Any audience (members are fully paginated, no size cap). Only subscribed members are read, so unsubscribed, cleaned, pending and archived members are never charged. **Incremental syncs.** Members changed since the last sync (`since_last_changed`). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back Mailchimp write-back is tag-based; no merge fields are written. ### Status tags `rv-status:` (prefix configurable), e.g. `rv-status:undeliverable`. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag (default `rv-invalid`). - **Unsubscribe**: Sets the member's status to unsubscribed. - **Delete**: Archives the member. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. --- # ActiveCampaign email verification Source: https://docs.rocketverifier.com/integrations/activecampaign > Verify ActiveCampaign contacts, write custom fields and status tags, and unsubscribe bad addresses from the synced list. ## Connect ActiveCampaign **Step 1** In RocketVerifier open **Dashboard → Integrations → ActiveCampaign**, paste the credentials below (ActiveCampaign → Settings → Developer) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Settings → Developer. | | API URL | Required | Your `https://.api-us1.com` (or `.activehosted.com`) URL from the same page. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All contacts or any list. **Incremental syncs.** Contacts updated since the last sync. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `RV_EMAIL_STATUS` - `RV_EMAIL_SUB_STATUS` - `RV_EMAIL_SCORE` - `RV_VERIFIED_AT` Custom contact fields, created on first use and attached to all lists. ### Status tags `rv-status:`. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag (default `rv-invalid`). - **Unsubscribe**: Unsubscribes the contact from the synced list. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. --- # Klaviyo email verification Source: https://docs.rocketverifier.com/integrations/klaviyo > Verify Klaviyo profiles, store the result as profile properties, suppress bad addresses and verify new sign-ups as they subscribe. ## Connect Klaviyo **Step 1** In RocketVerifier open **Dashboard → Integrations → Klaviyo**, paste the credentials below (a Klaviyo private API key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | A Klaviyo private API key (Settings → API keys) that can read lists and profiles and write profiles. For auto-verify, add `webhooks:read`, `webhooks:write`, `events:read` and `profiles:read`. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All profiles or any list. Profiles that cannot receive email marketing (unsubscribed or suppressed) are skipped and never charged. **Incremental syncs.** Profiles updated since the last sync. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Custom profile properties, written per profile. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Suppress**: Suppresses the profile with a bulk suppression job (100 emails per job). Profiles that were already suppressed or opted out are left alone, so Undo only lifts suppressions RocketVerifier added. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Auto-verify new contacts Turn on **Auto-verify new contacts**. RocketVerifier creates one account-wide Klaviyo webhook for the `subscribed_to_email_marketing` event (what a Klaviyo sign-up form with a list produces), optionally limited to the lists you pick. Each delivery's `Klaviyo-Signature` (HMAC-SHA256 of the body and `Klaviyo-Timestamp`) is checked, timestamps older than 5 minutes are rejected, and the new profile's email is read from the API before it is verified and written back. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Requirements and limits - Klaviyo offers its Webhooks API to accounts with Advanced KDP. Other accounts keep new sign-ups verified with a scheduled incremental sync of the form's list. --- # Brevo email verification Source: https://docs.rocketverifier.com/integrations/brevo > Verify Brevo (Sendinblue) contacts, write contact attributes and blacklist bad addresses. ## Connect Brevo **Step 1** In RocketVerifier open **Dashboard → Integrations → Brevo**, paste the credentials below (a Brevo API v3 key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Brevo → SMTP & API → API keys (v3). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All contacts or any list. **Incremental syncs.** Contacts modified since the last sync (`modifiedSince`). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `RV_EMAIL_STATUS` - `RV_EMAIL_SUB_STATUS` - `RV_EMAIL_SCORE` - `RV_VERIFIED_AT` Contact attributes, created on first use (score as a number). Written 100 contacts per batch. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Suppress**: Blocklists the contact (`emailBlacklisted`) in the same batch call. Undo lifts it again. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. --- # MailerLite email verification Source: https://docs.rocketverifier.com/integrations/mailerlite > Verify MailerLite subscribers, write custom fields, unsubscribe or move bad addresses to a group. ## Connect MailerLite **Step 1** In RocketVerifier open **Dashboard → Integrations → MailerLite**, paste the credentials below (a token for the new MailerLite API) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | MailerLite → Integrations → API (new MailerLite, connect.mailerlite.com). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All subscribers or any group. **Incremental syncs.** Subscribers whose `updated_at` is after the last sync (filtered by RocketVerifier; MailerLite has no server-side filter). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Custom fields (labels RV Email Status etc.), created on first use. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Unsubscribe**: Sets the subscriber to unsubscribed. - **Move to list**: Adds the subscriber to the group you pick. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. --- # Kit (ConvertKit) email verification Source: https://docs.rocketverifier.com/integrations/kit > Verify Kit subscribers, write custom fields and status tags, and unsubscribe bad addresses. ## Connect Kit (ConvertKit) **Step 1** In RocketVerifier open **Dashboard → Integrations → Kit (ConvertKit)**, paste the credentials below (a Kit v4 API key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Kit → Settings → Developer → API keys (v4). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All subscribers or subscribers with a given tag. Only active subscribers are read; cancelled, bounced and complained subscribers are never charged. **Incremental syncs.** Subscribers updated since the last sync. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `RV Email Status` - `RV Email Sub-status` - `RV Email Score` - `RV Verified At` - `rv_email_recommendation` Custom fields, created on first use. ### Status tags `rv-status:`. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag (default `rv-invalid`). - **Unsubscribe**: Unsubscribes the subscriber. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Requirements and limits - Kit allows API keys 120 requests per minute, and write-back on large lists runs at that pace. --- # Constant Contact email verification Source: https://docs.rocketverifier.com/integrations/constant_contact > Verify Constant Contact contacts, write custom fields and tags, and unsubscribe bad addresses. ## Connect Constant Contact **Step 1** In RocketVerifier open **Dashboard → Integrations → Constant Contact** and click **Connect**. You are sent to Constant Contact to approve access, then back to the dashboard. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** All contacts or any list. Only active contacts are read. **Incremental syncs.** Contacts updated since the last sync (`updated_after`). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Custom fields, created on first use. ### Status tags `rv-status:`. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag (default `rv-invalid`). - **Unsubscribe**: Sets the contact's permission to send to unsubscribed. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. --- # GetResponse email verification Source: https://docs.rocketverifier.com/integrations/getresponse > Verify GetResponse contacts and write hidden custom fields and status tags. ## Connect GetResponse **Step 1** In RocketVerifier open **Dashboard → Integrations → GetResponse**, paste the credentials below (a GetResponse API key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | A GetResponse API key (Integrations and API → API in GetResponse). | | MAX domain | Optional | GetResponse MAX accounts only: your MAX domain. | | MAX region | Optional | GetResponse MAX accounts only: `us` or `pl`. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All contacts or any list (GetResponse calls lists "campaigns"). **Incremental syncs.** Contacts changed since the last sync. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Hidden text custom fields, created on first use. ### Status tags `rv_status_` (GetResponse tags only allow letters, digits and underscores, so `rv-status:` becomes `rv_status_`). Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag. - **Delete**: Deletes the contact (GetResponse has no per-contact API unsubscribe). - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Requirements and limits - GetResponse MAX accounts connect with their MAX domain and region. --- # Drip email verification Source: https://docs.rocketverifier.com/integrations/drip > Verify Drip subscribers, write custom fields and status tags, and unsubscribe bad addresses. ## Connect Drip **Step 1** In RocketVerifier open **Dashboard → Integrations → Drip**, paste the credentials below (your Drip API token and account id) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Your Drip API token (Drip user settings). | | Account id | Required | Your numeric Drip account id (it is part of your Drip app URLs). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All subscribers, an email series campaign, or subscribers with a tag. Only active subscribers are read. **Incremental syncs.** New subscribers since the last sync (`subscribed_after`); Drip has no "updated since" filter. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Subscriber custom fields, sent in batches of up to 1,000. ### Status tags `rv-status:`; the other status tags are removed. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag. - **Unsubscribe**: Unsubscribes the subscriber (batches of 1,000). - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Requirements and limits - Drip processes batches asynchronously, so the sync report counts a subscriber as updated once Drip accepts its batch. --- # Smartlead email verification Source: https://docs.rocketverifier.com/integrations/smartlead > Verify campaign leads in Smartlead and pause or unsubscribe bad ones before they bounce. ## Connect Smartlead **Step 1** In RocketVerifier open **Dashboard → Integrations → Smartlead**, paste the credentials below (your Smartlead API key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Your Smartlead API key (Smartlead settings). Smartlead only accepts it as a query parameter; it is never written to logs. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** Any campaign. **Incremental syncs.** Leads created since the last sync (Smartlead has no "updated since" filter). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_status` - `rv_sub_status` - `rv_score` - `rv_verified_at` - `rv_recommendation` Lead custom fields. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Pause in campaigns**: Pauses the lead in the campaign. Undo resumes it. - **Unsubscribe**: Unsubscribes the lead. - **Delete**: Removes the lead from the campaign. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Campaign safety net Turn on **Campaign safety net** and RocketVerifier checks Smartlead every hour for leads newly added to running, paused and draft campaigns, verifies them and pauses invalid and disposable leads before they are emailed. Campaigns that have not launched yet get every lead checked. Each new lead costs 1 credit and leads already checked are free. --- # Instantly email verification Source: https://docs.rocketverifier.com/integrations/instantly > Verify Instantly campaign leads and block bad addresses workspace-wide. ## Connect Instantly **Step 1** In RocketVerifier open **Dashboard → Integrations → Instantly**, paste the credentials below (an Instantly API v2 key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | An Instantly API v2 workspace key (Instantly settings → API keys). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** Any campaign. **Incremental syncs.** Leads updated since the last sync (filtered by RocketVerifier). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_status` - `rv_sub_status` - `rv_score` - `rv_verified_at` - `rv_recommendation` Lead custom variables, merged with the variables the lead had when it was read. An edit made in Instantly between the sync and the write-back is replaced by that merged set. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Unsubscribe**: Adds the address to the workspace block list. - **Delete**: Deletes the lead. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Campaign safety net Turn on **Campaign safety net** and RocketVerifier checks Instantly every hour for leads newly added to running, paused and draft campaigns, verifies them and block-lists invalid and disposable leads before they are emailed. Campaigns that have not launched yet get every lead checked. Each new lead costs 1 credit and leads already checked are free. --- # lemlist email verification Source: https://docs.rocketverifier.com/integrations/lemlist > Verify lemlist campaign leads, store the result as lead variables, and pause or unsubscribe bad addresses. ## Connect lemlist **Step 1** In RocketVerifier open **Dashboard → Integrations → lemlist**, paste the credentials below (your lemlist API key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Your lemlist API key (lemlist settings → Integrations). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** Any campaign. **Incremental syncs.** Leads added to the campaign since the last sync. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rvStatus` - `rvSubStatus` - `rvScore` - `rvVerifiedAt` - `rvRecommendation` Lead variables. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Pause in campaigns**: Pauses the lead in that campaign. Undo starts it again. - **Unsubscribe**: Adds the address to the team-wide unsubscribe list. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Campaign safety net Turn on **Campaign safety net** and RocketVerifier checks lemlist every hour for leads newly added to running, paused and draft campaigns, verifies them and pauses invalid and disposable leads before they are emailed. Campaigns that have not launched yet get every lead checked. Each new lead costs 1 credit and leads already checked are free. --- # Apollo.io email verification Source: https://docs.rocketverifier.com/integrations/apollo > Verify Apollo contacts and sequence members, record the result in custom fields or as a list label, and stop bad addresses in sequences. ## Connect Apollo.io **Step 1** In RocketVerifier open **Dashboard → Integrations → Apollo.io**, paste the credentials below (an Apollo master API key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | An Apollo API key created as a master key; a master key is required to update contacts. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All contacts, any contact list, or any sequence (its active members). **Incremental syncs.** Contacts updated since the last sync. Sequences: contacts added since the last sync. Apollo caps one search at 50,000 records. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Written to typed custom fields with these names (or the labels RV Email Status, RV Email Sub-status and so on). Create them once in Apollo's settings; Apollo has no API to create them. ### Status tags Without those fields the status is written as the list label `rv-status:`; the contact's existing lists are kept. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action label. - **Pause in campaigns**: Marks the contact as finished in the synced sequence, so it gets no further steps. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Campaign safety net Turn on **Campaign safety net** and RocketVerifier checks Apollo.io every hour for leads newly added to running, paused and draft campaigns, verifies them and pauses invalid and disposable leads before they are emailed. Campaigns that have not launched yet get every lead checked. Each new lead costs 1 credit and leads already checked are free. --- # Reply.io email verification Source: https://docs.rocketverifier.com/integrations/replyio > Verify Reply.io contacts and finish or opt out bad addresses from your sequences. ## Connect Reply.io **Step 1** In RocketVerifier open **Dashboard → Integrations → Reply.io**, paste the credentials below (your Reply.io API key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Create the contact custom fields below in Reply (Settings → Custom fields); Reply ignores unknown keys. **Step 3** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Your Reply.io API key (from Reply's API settings). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All contacts or any campaign. **Incremental syncs.** Contacts updated since the last sync; for a campaign, contacts added to it since the last sync (filtered by RocketVerifier). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Contact custom fields (create them in Reply first). Each write checks that the contact still exists, so a contact deleted after the read is never re-created. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Pause in campaigns**: Pauses the contact in the synced campaign's sequence (Undo sets it back to active). For contacts read from All contacts, marks the contact as finished in all sequences. - **Unsubscribe**: Opts the contact out. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Campaign safety net Turn on **Campaign safety net** and RocketVerifier checks Reply.io every hour for leads newly added to running, paused and draft campaigns, verifies them and pauses invalid and disposable leads before they are emailed. Campaigns that have not launched yet get every lead checked. Each new lead costs 1 credit and leads already checked are free. --- # Woodpecker email verification Source: https://docs.rocketverifier.com/integrations/woodpecker > Verify Woodpecker prospects, write the result into snippet fields, and pause or blacklist bad addresses. ## Connect Woodpecker **Step 1** In RocketVerifier open **Dashboard → Integrations → Woodpecker**, paste the credentials below (your Woodpecker API key) and click **Connect**. They are validated against the platform before anything is saved. **Step 2** Map the result values you want to free snippets in the integration settings. **Step 3** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Your Woodpecker API key (from Woodpecker's API key settings). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All prospects or any campaign. **Incremental syncs.** Prospects updated since the last sync (filtered by RocketVerifier). ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `snippet1 to snippet15 (the ones you map)` Woodpecker prospects have 15 free-text snippets that templates can merge into emails, so nothing is written until you map a value to a free snippet in the integration settings (for example status to `snippet10` and score to `snippet11`). Prospects are matched by id and only the mapped snippets change. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Pause in campaigns**: Sets the prospect to PAUSED in the synced campaign. - **Unsubscribe**: Sets the prospect's status to BLACKLIST so it is never contacted again. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Campaign safety net Turn on **Campaign safety net** and RocketVerifier checks Woodpecker every hour for leads newly added to running, paused and draft campaigns, verifies them and pauses invalid and disposable leads before they are emailed. Campaigns that have not launched yet get every lead checked. Each new lead costs 1 credit and leads already checked are free. --- # Outreach email verification Source: https://docs.rocketverifier.com/integrations/outreach > Verify Outreach prospects, tag them with their status, pause bad ones in their sequences and verify new prospects as they are created. ## Connect Outreach **Step 1** In RocketVerifier open **Dashboard → Integrations → Outreach** and click **Connect**. You are sent to Outreach to approve access, then back to the dashboard. RocketVerifier asks for `prospects.all`, `sequences.read`, `sequenceStates.all` and `webhooks.all`. **Step 2** Pick the source to sync, the schedule and the write-back options in the integration settings, then click **Sync now** or wait for the schedule. Tokens are stored encrypted and refreshed automatically when the platform issues expiring tokens. If access is revoked, the integration is marked as needing reauthorization and you reconnect it from the dashboard. ## What it syncs **Sources.** All prospects, or any sequence (its prospects). The email verified is the first address in the prospect's `emails`. **Incremental syncs.** All prospects: prospects whose `updatedAt` is after the last sync. Sequences: prospects added to the sequence since the last sync. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `custom1 to custom150 (the ones you map)` Outreach prospects have 150 fixed custom fields that the API does not create or rename, so nothing is written to them until you map a value to a free field in the integration settings (e.g. status to `custom12`). Values are written as text. ### Status tags `rv-status:` in the prospect's tags; earlier `rv-status:` tags are replaced. Tags and mapped fields are written in one update per prospect. Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Add tag**: Adds the action tag (default `rv-invalid`). - **Pause in campaigns**: Pauses the prospect's active sequence states: in the synced sequence, or in every sequence when syncing all prospects. Undo resumes them. - **Unsubscribe**: Sets `optedOut` to true. Undo sets it back to false. - **Delete**: Deletes the prospect. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Campaign safety net Turn on **Campaign safety net** and RocketVerifier checks Outreach every hour for leads newly added to running, paused and draft campaigns, verifies them and pauses invalid and disposable leads before they are emailed. Campaigns that have not launched yet get every lead checked. Each new lead costs 1 credit and leads already checked are free. ## Auto-verify new contacts Turn on **Auto-verify new contacts**. RocketVerifier registers a `prospect` `created` webhook with a per-integration secret. Each delivery's `Outreach-Webhook-Signature` (hex HMAC-SHA256 of the raw body) is checked, events are de-duplicated by prospect id, and the prospect is re-read when the event carries no email. Each new contact costs 1 credit. Addresses this integration verified recently (30 days by default) are skipped, and webhook events are de-duplicated for 24 hours, so platform retries never charge twice. Turn on **Send an email.verified webhook for each new contact** to receive every result as an [`email.verified`](https://docs.rocketverifier.com/api/webhooks) event with `source` set to the platform. ## Requirements and limits - Pause acts on active sequence states only. Prospects in a draft sequence are reported as skipped. - Outreach allows 10,000 API requests per hour per user, so write-back on large prospect sets runs at that pace. --- # SendGrid email verification Source: https://docs.rocketverifier.com/integrations/sendgrid > Import SendGrid bounces and spam reports into your suppression list (and trigger bounce-guarantee refunds), and verify Marketing Campaigns contacts. ## Connect SendGrid **Step 1** In RocketVerifier open **Dashboard → Integrations → SendGrid**, paste the credentials below (a SendGrid API key) and click **Connect**. They are validated against the platform before anything is saved. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | SendGrid → Settings → API Keys. Suppressions read access is needed for the bounce feed, Marketing read access for contact syncs. | | Event webhook verification key | Optional | Settings → Mail Settings → Event Webhook → Signed Event Webhook (public key). Needed to accept real-time events. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** All Marketing Campaigns contacts or any list (read through SendGrid's contact export). **Incremental syncs.** SendGrid has no change filter, so an incremental sync reads the whole source. Contacts verified within the skip window are still skipped. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back Contact syncs are read-only: results appear in RocketVerifier, nothing is written back to SendGrid. ## Bounce feed setup The webhook URL is shown on the integration page in the dashboard and has this form: ```text https://api.rocketverifier.com/webhooks/connectors/sendgrid/{integration_id} ``` **Step 1** Copy the webhook URL shown on the integration page in the dashboard. **Step 2** In SendGrid open **Settings → Mail Settings → Event Webhook**, paste the URL as the HTTP POST URL and select the **Bounced**, **Blocked** and **Spam Reports** events. **Step 3** Turn on **Signed Event Webhook**, copy the verification key and paste it into the integration's *Event webhook verification key* field. Unsigned or wrongly signed events are rejected. **Mapping.** `bounce` → hard bounce, `blocked` → soft bounce, `spamreport` → complaint. Events are de-duplicated on `sg_event_id`, so SendGrid's retries are harmless. **Polling.** Even without the webhook, RocketVerifier reads the bounce and spam-report suppression lists once a day. --- # Mailgun email verification Source: https://docs.rocketverifier.com/integrations/mailgun > Import Mailgun bounces and complaints, and verify mailing-list members with results stored as member variables. ## Connect Mailgun **Step 1** In RocketVerifier open **Dashboard → Integrations → Mailgun**, paste the credentials below (a Mailgun private API key, region and sending domain) and click **Connect**. They are validated against the platform before anything is saved. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | Mailgun → API Security → private API key. | | Region | Required | US (`api.mailgun.net`) or EU (`api.eu.mailgun.net`). | | Sending domain | Optional | e.g. `mg.example.com`. Bounces and complaints are imported from this domain. | | Webhook signing key | Optional | Sending → Webhooks → HTTP webhook signing key. Needed to accept real-time webhooks. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## What it syncs **Sources.** Any mailing list. **Incremental syncs.** Mailgun has no change filter, so an incremental sync reads the whole source. Contacts verified within the skip window are still skipped. ## Schedules and credits - **Schedule:** manual, daily, weekly or monthly. **Sync now** starts a run immediately. One sync runs per integration at a time, and an address already on its way through another run is never charged twice. - **Mode:** *Full* checks every contact in the source except those verified in the last *N* days (default 30, range 0 to 365). *Incremental* checks only contacts changed since the last sync. Turn on per-status intervals to re-check unknown and catch-all addresses sooner than valid ones. - **Credits:** each sync is a regular verification job at 1 credit per unique address. `unknown` results are refunded when the job completes. Addresses you verified recently anywhere in RocketVerifier are written back from that result for free. If the balance is too low, the sync stops with `insufficient_credits` before anything is charged. - **Quarantine:** optionally re-check risky, catch-all and unknown contacts automatically every 1 to 90 days (default 14), so each one moves to Send or Remove once the result is clear. - **Results** are written back when the job completes. The sync history in the dashboard shows updated, failed and skipped counts for every run, and a finished run fires the `integration.sync.completed` webhook event. ## Write-back ### Status fields - `rv_email_status` - `rv_email_sub_status` - `rv_email_score` - `rv_verified_at` - `rv_email_recommendation` Member variables (`vars`). Status is one of `deliverable`, `undeliverable`, `risky` or `unknown`, and sub-status is a [`sub_status`](https://docs.rocketverifier.com/results#sub-status) value (`none` when there is no extra detail). Score runs from 0 to 100, verified-at is an ISO 8601 UTC timestamp, and recommendation is `send`, `review` or `remove` (valid is send; invalid and disposable are remove; risky, catch-all and unknown are review). Field names can be changed in the integration settings, and clearing a name stops that field from being written. ## Actions by result Pick an action for each result type in the integration settings: *Invalid*, *Disposable*, *Risky*, *Catch-all*, *Unknown* or *Valid*. Actions run after the write-back. - **Unsubscribe**: Sets the member to `subscribed=no`. - **Safe by default:** unsubscribe, suppress and delete never apply to catch-all or unknown results, whatever the rule says. Those contacts are often real people, so they can be tagged, moved or paused instead. - **Preview before acting** writes the results as usual but holds the actions until you approve the run in the sync history. - **Undo this run** reverses the actions the platform allows to be reversed, and every run keeps a CSV backup of the contacts it changed. ## Bounce feed setup The webhook URL is shown on the integration page in the dashboard and has this form: ```text https://api.rocketverifier.com/webhooks/connectors/mailgun/{integration_id} ``` **Step 1** Copy the webhook URL shown on the integration page in the dashboard. **Step 2** In Mailgun open **Sending → Webhooks** for the sending domain and add the URL for the **Permanent failure**, **Temporary failure** and **Spam complaints** events. **Step 3** Paste the domain's **HTTP webhook signing key** into the integration settings. Deliveries are checked against it; replays and deliveries older than 12 hours are rejected. **Mapping.** Permanent failure → hard bounce, temporary failure → soft bounce, complained → complaint. **Polling.** With a sending domain set, RocketVerifier also reads the domain's bounces and complaints once a day. --- # Amazon SES email verification Source: https://docs.rocketverifier.com/integrations/ses > Import Amazon SES bounce and complaint notifications through an SNS HTTPS subscription. ## Connect Amazon SES **Step 1** In RocketVerifier open **Dashboard → Integrations → Amazon SES**, enter the ARNs of the SNS topics that will deliver notifications (one per line) and click **Connect**. No AWS credentials are needed. | Field | Required | Where to find it | | --- | --- | --- | | SNS topic ARNs | Required | e.g. `arn:aws:sns:us-east-1:123456789012:ses-bounces`. Only notifications from these topics are accepted. | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## Write-back Amazon SES is a bounce feed only; it has no contacts to sync. ## Bounce feed setup The webhook URL is shown on the integration page in the dashboard and has this form: ```text https://api.rocketverifier.com/webhooks/connectors/ses/{integration_id} ``` **Step 1** In SES, send **Bounce** and **Complaint** notifications to an SNS topic: per identity (Notifications tab) or with a configuration set event destination. **Step 2** In SNS, create an **HTTPS** subscription on that topic with the webhook URL shown on the integration page. RocketVerifier confirms the subscription automatically. **Step 3** Make sure the topic's ARN is listed in the integration settings. **Mapping.** Permanent bounces → hard bounce, transient bounces → soft bounce, complaints → complaint. Every message's SNS signature is verified (certificates only from `sns..amazonaws.com`), messages older than 6 hours are rejected and message ids are de-duplicated. ## Requirements and limits - SES bounces and complaints go onto your suppression list. Bounce-guarantee refunds are confirmed against the sending provider's own API, which SendGrid, Mailgun and Postmark offer, so connect one of those to claim refunds. --- # Postmark email verification Source: https://docs.rocketverifier.com/integrations/postmark > Import Postmark bounces and spam complaints into your suppression list. ## Connect Postmark **Step 1** In RocketVerifier open **Dashboard → Integrations → Postmark**, paste the credentials below (a Postmark Server API token and the basic-auth credentials for the webhook) and click **Connect**. They are validated against the platform before anything is saved. | Field | Required | Where to find it | | --- | --- | --- | | API key | Required | The Server API token (Postmark → Server → API Tokens). | | Webhook username / password | Optional | Credentials you choose for the bounce webhook URL (Postmark supports only HTTP Basic auth on webhooks). | Credentials are stored encrypted and are only ever sent to the platform's own API hosts. ## Write-back Postmark is a bounce feed only. ## Bounce feed setup The webhook URL is shown on the integration page in the dashboard and has this form: ```text https://api.rocketverifier.com/webhooks/connectors/postmark/{integration_id} ``` **Step 1** Copy the webhook URL from the integration page and add your username and password to it: `https://:@api.rocketverifier.com/webhooks/connectors/postmark/{integration_id}`. **Step 2** In Postmark open **Server → Message Stream → Webhooks → Add webhook**, paste that URL and enable **Bounce** (and **Spam Complaint**). **Step 3** Enter the same username and password in the integration settings. Deliveries with other credentials are rejected. **Mapping.** HardBounce, BadEmailAddress and similar → hard bounce; SoftBounce, Transient, DnsError and similar → soft bounce; SpamComplaint → complaint. De-duplicated on the bounce id. **Polling.** RocketVerifier also reads Postmark's bounces API once a day, one day at a time. --- # Build an app with RocketVerifier Connect Source: https://docs.rocketverifier.com/oauth > RocketVerifier Connect is a standard OAuth 2.0 provider with PKCE. Your users click Connect RocketVerifier, approve your app on a consent screen, and you call the same API with an rv_at_ access token instead of an API key. Every call is billed to the account that connected, so building and running an app costs you nothing. Connect is how SaaS products, plugins, CRMs, AI agents and MCP clients add email verification on their users' accounts. One button replaces "paste your API key here", and the user stays in control of what your app can do and spend. ## How Connect works A Connect integration is three steps: send the user to the consent screen, exchange the code for tokens, then call the API with the access token. **Step 1. The user clicks Connect RocketVerifier** Your server builds an authorize URL with the scopes you need, a `state` value and a PKCE challenge, and redirects the browser to `https://app.rocketverifier.com/oauth/authorize`. **Step 2. The user approves on the consent screen** They sign in, pick their personal account or an organization they own or administer, optionally set a monthly credit cap for your app, and click Allow. RocketVerifier redirects back to your `redirect_uri` with a single-use code. **Step 3. Your app calls the API as the user** Your server exchanges the code for an access token (`rv_at_`, valid 1 hour) and a refresh token (`rv_rt_`, valid 90 days, rotated on every use). Send the access token as `Authorization: Bearer rv_at_...` to `https://api.rocketverifier.com/v1`, exactly like an API key. The [OAuth quickstart](https://docs.rocketverifier.com/oauth/quickstart) walks through all three steps with cURL, Node.js and Python. ## Choose OAuth or an API key Use an API key when the account is yours. Use OAuth when the account belongs to someone else. | | API key | OAuth (Connect) | | --- | --- | --- | | Whose account | Yours | Each of your users, personal or organization | | Who pays for credits | You | The account that connected | | How access is granted | A key copied from the dashboard | One click on a consent screen | | What it can do | Scopes chosen when the key is created | Scopes the user approved, plus an optional monthly credit cap | | Lifetime | Until revoked or expired | 1 hour access token, 90 day rotating refresh token | | How the user disconnects | Deletes the key | Settings, Connected apps, one click | | Best for | Your backend, scripts, internal tools | SaaS products, plugins, AI agents, MCP clients | Both credentials use the same `Authorization: Bearer` header and the same endpoints, so every page in the [API reference](https://docs.rocketverifier.com/api) applies to both. API keys are covered in [authentication](https://docs.rocketverifier.com/authentication). ## Who pays for verifications Every call made with an OAuth token is billed to the account that connected, and the developer pays nothing. - **Personal connection:** the call uses the user's credits and rate limit. When the user belongs to an organization with credit pooling on, personal usage draws from that organization's pool first, and the consent screen says so. - **Organization connection:** the call acts as the organization. It uses the organization's credit pool, its rate limit bucket and its IP allowlist. Only owners and admins can connect an organization, and the connection stops working if the person who approved it is no longer an owner or admin. - **Monthly credit cap:** the user can cap what your app spends each month on the consent screen, and change the cap later under Settings, Connected apps. Past the cap, calls that cost credits return `402 api_key_spend_cap_reached`. - **Free results stay free:** `unknown` results, sandbox addresses and suppression list hits cost nothing, exactly as with an API key. ## What Connect includes Connect implements the standards your OAuth library already speaks, so most integrations need only the issuer URL. - Authorization code flow with PKCE `S256` (RFC 6749, RFC 7636), with the `iss` callback parameter (RFC 9207). - Refresh token rotation with reuse detection: a replayed refresh token ends the connection. - Revocation (RFC 7009), introspection (RFC 7662), server metadata (RFC 8414) and dynamic client registration (RFC 7591). - Confidential clients (server apps with a client secret) and public clients (single page, mobile, desktop, CLI and MCP apps) using PKCE. - Self-serve registration in [Developer apps](https://app.rocketverifier.com/dashboard/developer/apps), with up to 10 apps per account. - A signed `grant.revoked` webhook when a user disconnects, so you can clean up at once. - OAuth helpers in the [Node.js](https://docs.rocketverifier.com/sdks/nodejs) and [Python](https://docs.rocketverifier.com/sdks/python) SDKs that build the PKCE URL, exchange the code and refresh expired tokens automatically. Every endpoint, parameter and error is in the [authorization reference](https://docs.rocketverifier.com/oauth/reference). ## Add the Connect RocketVerifier button Use the official button so users recognize it instantly. Both versions are 248 by 48 pixel SVG files you can host yourself. - Light backgrounds: [connect-rocketverifier-light.svg](https://docs.rocketverifier.com/brand/connect-rocketverifier-light.svg) - Dark backgrounds: [connect-rocketverifier-dark.svg](https://docs.rocketverifier.com/brand/connect-rocketverifier-dark.svg) HTML: ```html Connect RocketVerifier ``` Point the link at a route on your server that generates `state` and the PKCE verifier, stores them in the user's session, and redirects to the authorize URL. Build the authorize URL on the server for every attempt rather than hard-coding it in the page. ## Build it with your AI coding assistant Paste one URL into Claude Code, Cursor, Copilot or any coding assistant and ask it to add Connect RocketVerifier to your app. Prompt: ```text Read https://docs.rocketverifier.com/build-an-integration.md and add a Connect RocketVerifier button to my app so users can verify their contacts. ``` The [build-an-integration.md](https://docs.rocketverifier.com/build-an-integration.md) file is one self-contained spec: endpoints, scopes, the PKCE flow, error handling, button assets and tested UI copy. See [docs for AI assistants](https://docs.rocketverifier.com/ai) for the other machine-readable formats. ## Connect AI assistants with OAuth Claude, ChatGPT and other MCP clients use the same flow to connect to the hosted MCP server at `https://api.rocketverifier.com/mcp` without an API key. Clients register themselves, so there is nothing to set up in the dashboard. Users who want to try it start at [Use RocketVerifier with AI assistants](https://docs.rocketverifier.com/mcp), and client developers start at [MCP connector with OAuth](https://docs.rocketverifier.com/oauth/mcp). ## Next steps - [OAuth quickstart](https://docs.rocketverifier.com/oauth/quickstart) Create an app and verify an email on a connected account in ten minutes. - [Scopes](https://docs.rocketverifier.com/oauth/scopes) Every scope, the endpoints it unlocks and the right set for your app. - [Security best practices](https://docs.rocketverifier.com/oauth/security) State, PKCE, token storage and safe refresh before you ship. - [App review and directory](https://docs.rocketverifier.com/oauth/review) Earn the Verified badge and a listing at rocketverifier.com/apps. ## Frequently asked questions ### Do I pay for the verifications my users run through my app? No. Calls made with an OAuth access token are billed to the account that connected, either the user's personal credits or their organization's. Developers pay nothing to build or run an app. ### Should I use OAuth or an API key? Use an API key when the RocketVerifier account is yours. Use OAuth when each of your users brings their own account, so they never paste a key into your product. ### Can I test OAuth without spending credits? Yes. Access tokens are live, and addresses at @sandbox.rocketverifier.com still return fixed results for free. Connect your own account while you build and verify sandbox addresses. ### Does my app work before it is reviewed? Yes. Every app works the moment you create it. Until it passes review, the consent screen shows an Unverified app badge and the app is not listed in the directory. --- # OAuth quickstart Source: https://docs.rocketverifier.com/oauth/quickstart > Create an app in Developer apps, send the user to https://app.rocketverifier.com/oauth/authorize with a PKCE challenge, exchange the returned code at /api/oauth/token, and call the API with the rv_at_ access token. Access tokens last one hour; refresh them with the rv_rt_ refresh token and save the new refresh token every time. This guide takes you from a new app to a verified email on a connected account. It runs the flow with cURL first so you see every request, then shows the same flow with the Node.js and Python SDKs. > **Note: Access tokens are live** > > > OAuth tokens act on a real account, so connect your own while you build. `GET /v1/me` is free, and addresses at `@sandbox.rocketverifier.com` return fixed results without spending a credit. > ## Create an app Register your app in the dashboard to get a client ID and, for server apps, a client secret. **Step 1. Open Developer apps** Go to [Developer apps](https://app.rocketverifier.com/dashboard/developer/apps) and click New app. **Step 2. Name the app and add a redirect URI** Enter a name (2 to 60 characters) and choose the client type. Pick **confidential** for an app with a server that can keep a secret, or **public** for single page, mobile, desktop and CLI apps, which authenticate with PKCE alone. For this guide add the redirect URI `http://localhost:3000/callback`. Redirect URIs match exactly, character for character. **Step 3. Copy the credentials** Copy the client ID (`rvapp_...`) and the client secret (`rv_cs_...`). The secret is shown once. You can rotate it on the app's page at any time, and the old secret stops working immediately. Shell: ```bash export RV_CLIENT_ID=rvapp_your_client_id export RV_CLIENT_SECRET=rv_cs_your_client_secret export RV_REDIRECT_URI=http://localhost:3000/callback ``` New apps can request `verify:single`, `verify:bulk`, `jobs:read`, `jobs:write`, `credits:read` and `account:read`. Enable `webhooks:manage`, `monitors:read` or `monitors:write` on the app's page before you request them. See [scopes](https://docs.rocketverifier.com/oauth/scopes). ## Generate a PKCE pair and a state value PKCE binds the authorization code to the session that asked for it: the verifier stays on your server and only its SHA-256 challenge goes in the URL. Shell: ```bash export VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64) export CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=') export STATE=$(openssl rand -hex 16) ``` The verifier is 43 to 128 characters from `A-Z a-z 0-9 - . _ ~`, and the challenge is its base64url SHA-256 without padding, always 43 characters. ## Send the user to the consent screen Open the authorize URL in a browser, sign in, pick an account and click Allow. Shell: ```bash echo "https://app.rocketverifier.com/oauth/authorize?response_type=code\ &client_id=$RV_CLIENT_ID\ &redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback\ &scope=verify%3Asingle%20account%3Aread\ &state=$STATE\ &code_challenge=$CHALLENGE\ &code_challenge_method=S256" ``` The browser lands on your redirect URI. Nothing is listening there yet, so copy the query string from the address bar. Redirect: ```text http://localhost:3000/callback?code=rv_ac_Xb3k...&state=3f9c2a8e...&iss=https%3A%2F%2Fapp.rocketverifier.com ``` Check that `state` equals the value you generated before you use the code. The code is single use and expires after 60 seconds. If the user clicks Cancel, the redirect carries `error=access_denied` instead of a code. ## Exchange the code for tokens POST the code and the PKCE verifier to the token endpoint, authenticating with your client ID and secret. cURL: ```bash curl -X POST https://app.rocketverifier.com/api/oauth/token \ -u "$RV_CLIENT_ID:$RV_CLIENT_SECRET" \ -d grant_type=authorization_code \ -d code=CODE_FROM_REDIRECT \ -d redirect_uri=$RV_REDIRECT_URI \ -d code_verifier=$VERIFIER ``` Response 200: ```json { "access_token": "rv_at_q8Zk2N...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "rv_rt_W4pLm9...", "scope": "verify:single account:read" } ``` `-u` sends the credentials with HTTP Basic (`client_secret_basic`). Public apps send `-d client_id=$RV_CLIENT_ID` and no secret. The `scope` field lists what the connection holds, so store it with the tokens and check it before you show a feature. ## Call the API as the user Send the access token in the `Authorization` header, exactly like an API key. cURL: ```bash export RV_TOKEN=rv_at_q8Zk2N... curl https://api.rocketverifier.com/v1/me \ -H "Authorization: Bearer $RV_TOKEN" ``` Response 200: ```json { "email": "maya@northwind.io", "name": "Maya Chen", "account_type": "personal", "organization": null, "credits": 12400, "auth_type": "oauth", "scopes": ["verify:single", "account:read"], "app": { "client_id": "rvapp_3kq9x2Lm", "name": "Northwind CRM", "monthly_credit_limit": 5000, "credits_used_this_month": 0 } } ``` Show this in your settings page, for example "Connected as maya@northwind.io, 12,400 credits". `GET /v1/me` needs `account:read` and works even at a zero balance. Now verify an address: cURL: ```bash curl -X POST https://api.rocketverifier.com/v1/verify \ -H "Authorization: Bearer $RV_TOKEN" \ -H "Content-Type: application/json" \ -d '{"email": "deliverable@sandbox.rocketverifier.com"}' ``` The response is the same result object an API key gets, described in [verify an email](https://docs.rocketverifier.com/api/verify). Swap in a real address to charge the connected account 1 credit. ## Refresh the access token Access tokens last one hour. When one expires, the API returns `401` with `WWW-Authenticate: Bearer error="invalid_token"`, and you trade the refresh token for a new pair. cURL: ```bash curl -X POST https://app.rocketverifier.com/api/oauth/token \ -u "$RV_CLIENT_ID:$RV_CLIENT_SECRET" \ -d grant_type=refresh_token \ -d refresh_token=rv_rt_W4pLm9... ``` > **Warning: Save the new refresh token every time** > > > Refresh tokens rotate on every use. The response carries a new `refresh_token` and the one you sent stops working. Sending a used refresh token again is treated as theft and revokes the whole connection, so store the new pair before you use it and run one refresh at a time per connection. > ## Run the same flow with an SDK The SDK helpers generate PKCE and `state`, build the URL, exchange the code, and refresh expired tokens automatically, reporting each new token set so you can save it. Node.js: ```bash npm install @rocketverifier/sdk express ``` Python: ```bash pip install rocketverifier flask ``` Node.js: ```js import express from "express"; import RocketVerifier, { OAuth, OAuthError } from "@rocketverifier/sdk"; const oauth = new OAuth({ clientId: process.env.RV_CLIENT_ID, // rvapp_... clientSecret: process.env.RV_CLIENT_SECRET, // rv_cs_..., server only redirectUri: "http://localhost:3000/callback", }); const pending = new Map(); // state -> codeVerifier. Use your session store in production. let saved = null; // Use your database in production, encrypted. const app = express(); // 1. The Connect button links here. app.get("/connect", (req, res) => { const { url, state, codeVerifier } = oauth.getAuthorizeUrl({ scopes: ["verify:single", "account:read"], }); pending.set(state, codeVerifier); res.redirect(url); }); // 2. RocketVerifier redirects back here. app.get("/callback", async (req, res) => { const { code, state, error } = req.query; if (error) return res.send(`Not connected: ${error}`); // access_denied when the user cancels const codeVerifier = pending.get(state); if (!codeVerifier) return res.status(400).send("Unknown state"); pending.delete(state); saved = await oauth.exchangeCode({ code, codeVerifier }); res.redirect("/me"); }); // 3. Call the API as the user. Expired tokens refresh automatically. app.get("/me", async (req, res) => { const rv = new RocketVerifier({ accessToken: saved.accessToken, refreshToken: saved.refreshToken, oauth, onTokenRefresh: (next) => { saved = next; }, // refresh tokens rotate: always save }); try { const me = await rv.getMe(); const result = await rv.verify("deliverable@sandbox.rocketverifier.com"); res.json({ connectedAs: me.email, credits: me.credits, status: result.status }); } catch (err) { if (err instanceof OAuthError && err.error === "invalid_grant") { return res.redirect("/connect"); // the connection is gone: connect again } throw err; } }); app.listen(3000, () => console.log("Open http://localhost:3000/connect")); ``` Python: ```python import os from flask import Flask, redirect, request, session from rocketverifier import RocketVerifier, OAuth, OAuthError oauth = OAuth( client_id=os.environ["RV_CLIENT_ID"], # rvapp_... client_secret=os.environ["RV_CLIENT_SECRET"], # rv_cs_..., server only redirect_uri="http://localhost:3000/callback", ) app = Flask(__name__) app.secret_key = os.environ["FLASK_SECRET_KEY"] saved = {} # Use your database in production, encrypted. @app.get("/connect") def connect(): auth = oauth.get_authorize_url(scopes=["verify:single", "account:read"]) session["rv_state"], session["rv_verifier"] = auth.state, auth.code_verifier return redirect(auth.url) @app.get("/callback") def callback(): if request.args.get("error"): return f"Not connected: {request.args['error']}" if request.args.get("state") != session.pop("rv_state", None): return "Unknown state", 400 tokens = oauth.exchange_code(code=request.args["code"], code_verifier=session.pop("rv_verifier")) saved["tokens"] = tokens return redirect("/me") @app.get("/me") def me(): tokens = saved["tokens"] rv = RocketVerifier( access_token=tokens.access_token, refresh_token=tokens.refresh_token, oauth=oauth, on_token_refresh=lambda new: saved.update(tokens=new), # refresh tokens rotate: always save ) try: profile = rv.get_me() result = rv.verify("deliverable@sandbox.rocketverifier.com") return {"connected_as": profile.email, "credits": profile.credits, "status": result.status} except OAuthError as err: if err.error == "invalid_grant": return redirect("/connect") # the connection is gone: connect again raise app.run(port=3000) ``` Without `refreshToken` and `oauth`, an expired token raises `InvalidTokenError` instead of refreshing. Call `oauth.revoke(refreshToken)` (`oauth.revoke(refresh_token)` in Python) to disconnect from your side. `AsyncRocketVerifier` in Python takes the same arguments, and `OAuth` has async twins such as `aexchange_code` and `arefresh`. ## Next steps - [Pick your scopes](https://docs.rocketverifier.com/oauth/scopes) Request the smallest set your features use. - [Handle grant.revoked](https://docs.rocketverifier.com/oauth/reference#handle-the-grantrevoked-webhook) Clean up the moment a user disconnects. - [Security checklist](https://docs.rocketverifier.com/oauth/security) Token storage, safe refresh and state checks before you ship. - [Get reviewed](https://docs.rocketverifier.com/oauth/review) Remove the Unverified badge and join the app directory. ## Frequently asked questions ### How long does the authorization code last? 60 seconds, and it works once. Exchange it as soon as your callback receives it. ### Why did my refresh fail with invalid_grant? The user disconnected your app, the refresh token expired after 90 days, or an old refresh token was sent again. Refresh tokens rotate on every use, so always store the newest one. Send the user through Connect again. ### Do I need PKCE if my app has a client secret? PKCE is required for public clients and recommended for every app. The SDK helpers always use it. ### Can I run this flow without spending credits? Yes. GET /v1/me is free, and addresses at @sandbox.rocketverifier.com return fixed results without charging the connected account. --- # Authorization reference Source: https://docs.rocketverifier.com/oauth/reference > RocketVerifier Connect is an OAuth 2.0 authorization server at https://app.rocketverifier.com with PKCE, refresh token rotation, revocation, introspection, dynamic client registration and RFC 8414 metadata. Access tokens last 1 hour, refresh tokens 90 days and rotate on every use, and authorization codes expire after 60 seconds. Connect follows OAuth 2.0 (RFC 6749) with PKCE (RFC 7636). Most OAuth libraries need only the issuer, `https://app.rocketverifier.com`, and read everything else from the [server metadata](#discover-endpoints-from-metadata). ## Endpoints The authorization server lives on the dashboard host, and the API that accepts the tokens lives on the API host. | Endpoint | URL | Standard | | --- | --- | --- | | Issuer | `https://app.rocketverifier.com` | | | Authorize | `https://app.rocketverifier.com/oauth/authorize` | RFC 6749 3.1 | | Token | `https://app.rocketverifier.com/api/oauth/token` | RFC 6749 3.2 | | Revoke | `https://app.rocketverifier.com/api/oauth/revoke` | RFC 7009 | | Introspect | `https://app.rocketverifier.com/api/oauth/introspect` | RFC 7662 | | Register | `https://app.rocketverifier.com/api/oauth/register` | RFC 7591 | | Server metadata | `https://app.rocketverifier.com/.well-known/oauth-authorization-server` | RFC 8414 | | Resource metadata (API) | `https://api.rocketverifier.com/.well-known/oauth-protected-resource` | RFC 9728 | | Resource metadata (MCP) | `https://api.rocketverifier.com/.well-known/oauth-protected-resource/mcp` | RFC 9728 | | API base URL | `https://api.rocketverifier.com/v1` | | ## Identifiers and lifetimes Every credential carries a fixed prefix so you can tell them apart in logs and secret scanners. | Value | Prefix | Lifetime | Notes | | --- | --- | --- | --- | | Client ID | `rvapp_` | Permanent | Public. Safe to ship in a browser, mobile or desktop app. | | Client secret | `rv_cs_` | Until rotated | Shown once and stored hashed. Rotating it in Developer apps ends the old secret immediately. | | Authorization code | `rv_ac_` | 60 seconds | Single use. | | Access token | `rv_at_` | 1 hour | Send as `Authorization: Bearer`, the same header as API keys. | | Refresh token | `rv_rt_` | 90 days | Rotated on every use. Reusing an old one revokes the connection. | Treat every value as an opaque string. RocketVerifier stores client secrets, codes and tokens only as SHA-256 hashes. ## Send the user to /oauth/authorize `GET https://app.rocketverifier.com/oauth/authorize` Redirect the user's browser here. RocketVerifier signs them in, shows the consent screen, then redirects to your `redirect_uri` with a code. - `response_type` (string, required): Always `code`. - `client_id` (string, required): Your app's `rvapp_...` ID. - `redirect_uri` (string): One of the app's registered redirect URIs, matched exactly: no wildcards, no prefix matching, and the query string counts. Loopback IP redirects (`http://127.0.0.1` and `http://[::1]`) match on any port, as RFC 8252 requires for native apps. Required when the app has more than one redirect URI. - `scope` (string): Space separated scopes, for example `verify:bulk jobs:read account:read`. Every scope must be enabled on the app. When omitted, the request asks for every scope the app allows, so always send it. See [scopes](https://docs.rocketverifier.com/oauth/scopes). - `state` (string): An unguessable value tied to the user's session, returned unchanged on the redirect. Always send it and compare it on the callback. - `code_challenge` (string): `BASE64URL(SHA256(code_verifier))` without padding, exactly 43 characters. Required for public clients and recommended for every app. - `code_challenge_method` (string): `S256`, required whenever you send `code_challenge`. Omitting it means `plain`, which is rejected. - `resource` (string): RFC 8707 resource indicator: `https://api.rocketverifier.com` or `https://api.rocketverifier.com/mcp`. MCP clients send it. Any other value fails with `invalid_target`. - `prompt` (string): `consent` shows the consent screen even when a verified app would skip it. ### What the consent screen shows The consent screen tells the user exactly who is asking, what for, and where they will land. - The app's name, logo and links, and a Verified badge or an Unverified app warning. Self-registered clients also show a note to connect only if the user started from that app. - Each requested scope in plain language, flagged when it spends credits. - An account picker: the user's personal account, or an organization where they are owner or admin. - An optional monthly credit cap for the app, prefilled from an existing connection. - The host of your redirect URI. A verified app skips the screen when the user's personal account already granted every requested scope. Unverified apps always show it. Requesting new scopes later adds them to the existing connection, which keeps everything it already had. ### Handle the callback A successful approval redirects to your `redirect_uri` with `code`, your `state` and `iss`. Success: ```text https://app.northwind.io/rocketverifier/callback?code=rv_ac_Xb3k...&state=3f9c2a8e&iss=https%3A%2F%2Fapp.rocketverifier.com ``` `iss` is always `https://app.rocketverifier.com` (RFC 9207). Check `state` first, then exchange the code within 60 seconds. Error: ```text https://app.northwind.io/rocketverifier/callback?error=access_denied&error_description=The+user+did+not+connect+their+RocketVerifier+account&state=3f9c2a8e&iss=https%3A%2F%2Fapp.rocketverifier.com ``` | `error` | When | | --- | --- | | `access_denied` | The user clicked Cancel. | | `invalid_request` | `code_challenge` is malformed or not `S256`, or a public client sent no PKCE challenge. | | `invalid_scope` | A scope is unknown or not enabled on the app. | | `invalid_target` | `resource` is not a RocketVerifier resource. | | `unsupported_response_type` | `response_type` is not `code`. | > **Warning: Untrusted requests never redirect** > > > When the `client_id` is missing or unknown, the app is suspended, or the `redirect_uri` is not registered for the app, RocketVerifier shows an error page and does not redirect. Redirecting to an unverified URI would hand the error, or a code, to an attacker. > ## Exchange codes and refresh tokens at /api/oauth/token `POST https://app.rocketverifier.com/api/oauth/token` The token endpoint takes `application/x-www-form-urlencoded` (JSON is accepted too) and returns JSON with `Cache-Control: no-store`. Call it from your server whenever a client secret is involved. ### Authenticate the client Confidential apps authenticate with their secret, and public apps send only their client ID and prove possession with PKCE. | Method | How | Use for | | --- | --- | --- | | `client_secret_basic` | `Authorization: Basic base64(client_id:client_secret)` | Server apps (recommended) | | `client_secret_post` | `client_id` and `client_secret` form fields | Server apps that cannot set headers | | `none` | `client_id` form field plus `code_verifier` | Public clients: single page, mobile, desktop, CLI and MCP apps | ### grant_type=authorization_code | Parameter | Required | Description | | --- | --- | --- | | `grant_type` | Yes | `authorization_code` | | `code` | Yes | The `rv_ac_` code from the redirect. Single use, valid 60 seconds. | | `redirect_uri` | When sent to authorize | The exact value sent to `/oauth/authorize`. | | `code_verifier` | With PKCE | The original verifier, 43 to 128 characters. | cURL: ```bash curl -X POST https://app.rocketverifier.com/api/oauth/token \ -u "$RV_CLIENT_ID:$RV_CLIENT_SECRET" \ -d grant_type=authorization_code \ -d code=rv_ac_Xb3k... \ -d redirect_uri=https://app.northwind.io/rocketverifier/callback \ -d code_verifier=$VERIFIER ``` ### grant_type=refresh_token | Parameter | Required | Description | | --- | --- | --- | | `grant_type` | Yes | `refresh_token` | | `refresh_token` | Yes | The newest `rv_rt_` token you received. | | `scope` | No | Must be within the granted scopes. The new tokens carry the connection's full granted scopes. | cURL: ```bash curl -X POST https://app.rocketverifier.com/api/oauth/token \ -u "$RV_CLIENT_ID:$RV_CLIENT_SECRET" \ -d grant_type=refresh_token \ -d refresh_token=rv_rt_W4pLm9... ``` ### Token response Both grants return a new access token and a new refresh token. Response 200: ```json { "access_token": "rv_at_q8Zk2N...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "rv_rt_W4pLm9...", "scope": "verify:bulk jobs:read account:read" } ``` `scope` lists every scope the connection holds, space separated. Store it with the tokens and check it before you show a feature that depends on a scope. ### Token errors Errors follow RFC 6749 section 5.2. Response 400: ```json { "error": "invalid_grant", "error_description": "Refresh token was already used; the connection has been revoked" } ``` | `error` | Status | Meaning and what to do | | --- | --- | --- | | `invalid_request` | 400 | A required parameter is missing, such as `code`, `refresh_token` or `grant_type`. Fix the request. | | `invalid_client` | 401 | Unknown client, wrong or missing secret, or the app is suspended. Check the credentials and any rotated secret. | | `invalid_grant` | 400 | The code is invalid, expired or used, `redirect_uri` or `code_verifier` does not match, or the refresh token is expired, revoked or reused. After a failed refresh, send the user through Connect again. | | `invalid_scope` | 400 | A refresh asked for a scope the user did not grant. | | `unsupported_grant_type` | 400 | Only `authorization_code` and `refresh_token` are supported. | | `slow_down` | 429 | Rate limit reached. Retry after the seconds in `error_description`. | ## Refresh token rotation and reuse detection Every refresh returns a new refresh token and retires the one you sent, and a retired token that comes back ends the connection. - A successful refresh invalidates the refresh token you sent. The previous access token keeps working until it expires. - When a used refresh token is presented again, RocketVerifier assumes it leaked and revokes the whole grant: every access and refresh token for that user, account and app stops working. Your app receives [grant.revoked](#handle-the-grantrevoked-webhook) with `reason: "refresh_token_reuse"`. - Two refreshes racing with the same token count as reuse. Save the new pair in one write before you use it, and run one refresh at a time per connection, as described in [security best practices](https://docs.rocketverifier.com/oauth/security#refresh-tokens-safely). - An authorization code used twice fails, and the tokens from the first exchange are revoked as well. - Each refresh token lasts 90 days from issue. A connection that goes 90 days without a refresh expires, and the user connects again. ## Call the API with an access token Access tokens use the same header, endpoints and response shapes as API keys. cURL: ```bash curl https://api.rocketverifier.com/v1/credits \ -H "Authorization: Bearer rv_at_q8Zk2N..." ``` | Status | `error.code` | Meaning and what to do | | --- | --- | --- | | 401 | `invalid_token` | The token expired or was revoked, the app was suspended, or an organization connection lost its admin. Refresh once, then reconnect if the refresh fails. | | 403 | `insufficient_scope` | The token is valid but lacks the scope for this endpoint. Ask the user to connect again with the extra scope. | | 403 | `insufficient_credits` | The connected account's balance is zero, so the request is refused before any check runs. | | 402 | `insufficient_credits` | The balance ran out while charging this request. | | 402 | `api_key_spend_cap_reached` | Your app reached the monthly credit cap the user set. `details` has `monthly_limit`, `used_this_month` and `required`. | | 403 | `ip_not_allowed` | An organization connection was used from an IP outside the organization's allowlist. | | 429 | `rate_limited` | The connected account's rate limit, or the organization's for organization connections. Wait for `Retry-After`. | 401 response: ```http HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer error="invalid_token", error_description="Access token has expired" { "error": { "code": "invalid_token", "message": "Access token has expired", "details": null } } ``` Tell the user about `402` and `403 insufficient_credits` rather than retrying. The shared error format is in [errors](https://docs.rocketverifier.com/errors), and the limits per plan are in [rate limits](https://docs.rocketverifier.com/rate-limits). ## Revoke a token at /api/oauth/revoke `POST https://app.rocketverifier.com/api/oauth/revoke` Revoking a refresh token ends the whole connection, and revoking an access token ends only that token. Authenticate the same way as at the token endpoint. The endpoint answers `200` with `{}` for every token, including unknown ones and tokens issued to other apps (RFC 7009). cURL: ```bash curl -X POST https://app.rocketverifier.com/api/oauth/revoke \ -u "$RV_CLIENT_ID:$RV_CLIENT_SECRET" \ -d token=rv_rt_W4pLm9... \ -d token_type_hint=refresh_token ``` Revoking from your side does not send `grant.revoked` to your own webhook, because your app started it. ## Inspect a token at /api/oauth/introspect `POST https://app.rocketverifier.com/api/oauth/introspect` Introspection (RFC 7662) tells a confidential app whether one of its own tokens is active. It requires the client secret, and any token that is unknown, expired, revoked, rotated or issued to another app returns `{"active": false}`. cURL: ```bash curl -X POST https://app.rocketverifier.com/api/oauth/introspect \ -u "$RV_CLIENT_ID:$RV_CLIENT_SECRET" \ -d token=rv_at_q8Zk2N... ``` Response 200: ```json { "active": true, "client_id": "rvapp_3kq9x2Lm", "scope": "verify:bulk jobs:read account:read", "token_type": "Bearer", "sub": "cm3k9x2v40000abcd1234efgh", "organization_id": null, "aud": "https://api.rocketverifier.com", "iss": "https://app.rocketverifier.com", "iat": 1793530800, "exp": 1793534400 } ``` `token_type` is `Bearer` for access tokens and `refresh_token` for refresh tokens. `sub` is the RocketVerifier user who connected, `organization_id` is set for organization connections, and `aud` appears when the authorization request carried a `resource`. ## Register a client at /api/oauth/register `POST https://app.rocketverifier.com/api/oauth/register` Dynamic client registration (RFC 7591) lets MCP clients and other tools register themselves without a developer account. It takes JSON client metadata and returns `201` with a new `client_id`. Clients registered this way start unverified, have no owner in the dashboard and are never listed in the directory. For an app you will publish, create it in [Developer apps](https://app.rocketverifier.com/dashboard/developer/apps) instead. The full request, response and rules are on the [MCP connector](https://docs.rocketverifier.com/oauth/mcp#register-a-client) page. ## Discover endpoints from metadata The server metadata document (RFC 8414) lists every endpoint and capability, and is cached for one hour. GET https://app.rocketverifier.com/.well-known/oauth-authorization-server: ```json { "issuer": "https://app.rocketverifier.com", "authorization_endpoint": "https://app.rocketverifier.com/oauth/authorize", "token_endpoint": "https://app.rocketverifier.com/api/oauth/token", "revocation_endpoint": "https://app.rocketverifier.com/api/oauth/revoke", "introspection_endpoint": "https://app.rocketverifier.com/api/oauth/introspect", "registration_endpoint": "https://app.rocketverifier.com/api/oauth/register", "scopes_supported": [ "verify:single", "verify:bulk", "jobs:read", "jobs:write", "credits:read", "account:read", "webhooks:manage", "monitors:read", "monitors:write" ], "response_types_supported": ["code"], "response_modes_supported": ["query"], "grant_types_supported": ["authorization_code", "refresh_token"], "code_challenge_methods_supported": ["S256"], "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"], "revocation_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"], "introspection_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"], "authorization_response_iss_parameter_supported": true, "service_documentation": "https://docs.rocketverifier.com/oauth" } ``` The API publishes protected resource metadata (RFC 9728) that points back to this issuer. MCP clients start there, as shown in [discover the authorization server](https://docs.rocketverifier.com/oauth/mcp#discover-the-authorization-server). ## Handle the grant.revoked webhook RocketVerifier POSTs `grant.revoked` to your app's webhook URL whenever a user disconnects or a refresh token is reused. Delete the stored tokens for that connection and show the Connect button again. POST to your app's webhook URL: ```json { "event_id": "5b0f0c1e-8a7d-4b9e-9f4e-2d6c1a3b7e90", "event": "grant.revoked", "timestamp": "2026-11-11T12:00:00.000Z", "data": { "grant_id": "cm3k9z8w10000wxyz5678abcd", "client_id": "rvapp_3kq9x2Lm", "user_email": "maya@northwind.io", "account_type": "personal", "organization_id": null, "reason": "user_disconnected" } } ``` | `reason` | When | | --- | --- | | `user_disconnected` | The user clicked Disconnect under Settings, Connected apps. | | `refresh_token_reuse` | A used refresh token was presented, so the connection was revoked. | Set the webhook URL (https only) on your app's page in Developer apps. Saving it creates a signing secret (`whsec_...`) that you reveal on the same page. Each delivery carries these headers: | Header | Value | | --- | --- | | `X-RocketVerifier-Signature` | `t=,v1=`, where `v1` is HMAC SHA-256 of `.` with the webhook secret | | `X-RocketVerifier-Timestamp` | The same Unix timestamp | | `X-RocketVerifier-Event-Id` | The `event_id` from the body | The scheme matches every other RocketVerifier webhook, so the SDK helpers verify it. Node.js: ```js import { verifyWebhookSignature } from "@rocketverifier/sdk"; app.post("/rocketverifier/webhook", express.raw({ type: "application/json" }), async (req, res) => { const header = req.get("X-RocketVerifier-Signature"); if (!verifyWebhookSignature(req.body, header, process.env.RV_APP_WEBHOOK_SECRET)) { return res.status(400).end(); } const event = JSON.parse(req.body); if (event.event === "grant.revoked") await db.connections.deleteByGrant(event.data.grant_id); res.status(200).end(); }); ``` Python: ```python from rocketverifier import verify_webhook_signature @app.post("/rocketverifier/webhook") def rocketverifier_webhook(): header = request.headers.get("X-RocketVerifier-Signature") if not verify_webhook_signature(request.get_data(), header, os.environ["RV_APP_WEBHOOK_SECRET"]): return "", 400 event = request.get_json() if event["event"] == "grant.revoked": db.connections.delete_by_grant(event["data"]["grant_id"]) return "", 200 ``` Both helpers reject timestamps more than 5 minutes old. Delivery is one attempt with a 5 second timeout, so answer quickly. An app that misses the event learns on its next call: the API returns `401 invalid_token` and the refresh returns `invalid_grant`. The token response does not carry `grant_id`, so match the event to your stored connection by `organization_id` for organization connections and by `user_email` for personal ones. Save both from [GET /v1/me](https://docs.rocketverifier.com/api/account) right after the user connects. ## Rate limits on OAuth endpoints The OAuth endpoints have their own limits, separate from the API's, and answer `429 slow_down` when one is reached. | Endpoint | Limit | | --- | --- | | Token | 300 requests per minute per IP, and 1,200 per minute per app | | Revoke | 300 requests per minute per IP | | Introspect | 600 requests per minute per IP | | Register | 20 requests per minute per IP | ## Frequently asked questions ### What happens if I send a used refresh token? RocketVerifier treats it as stolen and revokes the whole connection. Every access and refresh token for that user and app stops working, and your app receives grant.revoked with reason refresh_token_reuse. ### Can I ask for fewer scopes when I refresh? The refresh request accepts a scope parameter, but it must be within what the user granted, and the new tokens carry the connection's full granted scopes. ### Why does the authorize page show an error instead of redirecting back? The client_id is unknown, the app is suspended, or the redirect_uri is not registered for the app. RocketVerifier never redirects to an unverified URI, so fix the app registration. ### Should I parse access tokens? No. Tokens are opaque strings. Treat everything after the prefix as random, and call the introspection endpoint when you need a token's details. --- # Scopes Source: https://docs.rocketverifier.com/oauth/scopes > A scope is one permission the user grants your app. RocketVerifier Connect has nine scopes, from verify:single to monitors:write, and each one unlocks a fixed set of /v1 endpoints. Request only what your features use; a call without the right scope returns 403 insufficient_scope. The backend checks the scope on every call, so the table below is the complete list of what each scope allows. ## All scopes Each scope unlocks the endpoints listed next to it, and the consent screen shows the user the plain language label. | Scope | Endpoints | What the user sees | Spends credits | | --- | --- | --- | --- | | `verify:single` | `POST /v1/verify`, `POST /v1/finder` | Verify email addresses one at a time | Yes | | `verify:bulk` | `POST /v1/verify/bulk`, `POST /v1/verify/bulk/upload`, `POST /v1/verify/bulk/{jobId}/preview`, `POST /v1/verify/bulk/{jobId}/confirm` | Run bulk verification jobs | Yes | | `jobs:read` | `GET /v1/jobs`, `GET /v1/jobs/{jobId}`, `GET /v1/jobs/{jobId}/progress`, `GET /v1/jobs/{jobId}/results`, `GET /v1/jobs/{jobId}/download` | See your verification jobs and their results | No | | `jobs:write` | `DELETE /v1/jobs/{jobId}` (cancel a job and refund unused credits) | Create and cancel verification jobs | No | | `credits:read` | `GET /v1/credits` | See your credit balance and usage | No | | `account:read` | `GET /v1/me` | See your email address, account name and credit balance | No | | `webhooks:manage` | `GET` and `POST /v1/webhooks`, `GET`, `PATCH` and `DELETE /v1/webhooks/{id}`, `POST /v1/webhooks/{id}/test`, `GET /v1/webhooks/{id}/logs`, `POST /v1/webhooks/{id}/rotate-secret` | Add and remove webhook endpoints on your account | No | | `monitors:read` | `GET /v1/monitors`, `GET /v1/monitors/{id}`, `GET /v1/monitors/{id}/runs` | See your list monitors | No | | `monitors:write` | `POST /v1/monitors`, `PATCH` and `DELETE /v1/monitors/{id}`, `POST /v1/monitors/{id}/run` | Create and change list monitors | Yes | These endpoints accept any valid access token with no scope: the domain tools under `/v1/tools` (disposable check, MX lookup, domain authentication, blacklist check), `GET /v1/webhooks/events` and `GET /v1/status`. Creating a bulk job needs `verify:bulk`, and reading its results needs `jobs:read`, so a list cleaning feature requests both. The `*` scope exists only for [API keys](https://docs.rocketverifier.com/authentication); an OAuth request that includes it fails with `invalid_scope`. ## Enable scopes on your app An app can request only the scopes enabled on it in [Developer apps](https://app.rocketverifier.com/dashboard/developer/apps). New apps start with six scopes enabled: `verify:single`, `verify:bulk`, `jobs:read`, `jobs:write`, `credits:read` and `account:read`. Turn on `webhooks:manage`, `monitors:read` or `monitors:write` on the app's page before you request them. Clients created through [dynamic registration](https://docs.rocketverifier.com/oauth/mcp#register-a-client) get the scopes in their registration request, or the same six when they send none. ## Request scopes Send scopes space separated in the `scope` parameter of the authorize URL, and read back what was granted from the token response. - **Request:** `scope=verify%3Abulk%20jobs%3Aread%20account%3Aread` in the [authorize URL](https://docs.rocketverifier.com/oauth/reference#send-the-user-to-oauthauthorize). The SDK helpers take a list: `scopes: ["verify:bulk", "jobs:read", "account:read"]`. - **Read back:** the token response carries `scope`, the full set the connection holds. Store it with the tokens and check it before you show a feature. - **Missing scope:** a call without the right scope returns `403` with `error.code` `insufficient_scope` and the message `Scope 'jobs:read' required`. - **Add scopes later:** send the user through the authorize URL again with the scope you need. The approved scopes are added to the existing connection for that account, so nothing it already had is lost. - **Always send `scope`:** an authorize request without it asks for every scope enabled on the app. ## Request the least privilege Ask for the scopes your features use today. A shorter consent screen gets more users to click Allow, and a smaller grant limits what a leaked token can do. > **Tip: Start with what you ship** > > > If your app verifies signups one at a time, request `verify:single` and `account:read`. Add `verify:bulk` and `jobs:read` the day you ship list imports. > > **Tip: Add account:read for a clear connected state** > > > `account:read` lets you show "Connected as maya@northwind.io, 12,400 credits" and warn before a job runs out of credits. It reads only the account summary and spends nothing. > > **Note: Reviewers check every scope** > > > During [app review](https://docs.rocketverifier.com/oauth/review), each requested scope must map to a feature a reviewer can find. Scopes that change the user's account, such as `webhooks:manage` and `monitors:write`, need a clear reason. > ## Common scope sets These sets cover the most common Connect integrations. | App type | Scopes | | --- | --- | | Signup form, chat or CRM that checks one address at a time | `verify:single account:read` | | List cleaning or contact import | `verify:bulk jobs:read account:read` | | Bulk jobs with completion webhooks instead of polling | `verify:bulk jobs:read webhooks:manage account:read` | | Reporting dashboard | `credits:read jobs:read monitors:read` | | AI agent or MCP client | `verify:single verify:bulk jobs:read jobs:write credits:read` | ## Frequently asked questions ### Which scopes can a new app request? New apps can request verify:single, verify:bulk, jobs:read, jobs:write, credits:read and account:read. Turn on webhooks:manage, monitors:read or monitors:write on the app's page in Developer apps before you request them. ### Can an OAuth app request every scope with *? No. The * scope exists only for API keys. OAuth apps list each scope they need. ### How do I add a scope after a user connected? Send the user through the authorize URL again with the new scope. The approved scopes are added to the existing connection, which keeps everything it already had. ### Do the domain tools need a scope? No. The /v1/tools endpoints, such as the disposable check, MX lookup and domain authentication check, accept any valid access token. --- # App review and the directory Source: https://docs.rocketverifier.com/oauth/review > Every Connect app works the moment you create it. Submitting it for review adds the Verified badge, removes the Unverified app warning from the consent screen, lets returning users skip consent, and lists the app in the public directory at rocketverifier.com/apps. Review is how users know an app is legitimate. It is optional for building and testing, and it is the step that turns a working integration into a trusted listing. ## What the Verified badge changes A verified app earns trust on the consent screen and a place in the directory. | | Unverified | Verified | | --- | --- | --- | | Works with every scope enabled on the app | Yes | Yes | | Consent screen | Unverified app warning | Verified badge next to your name | | Returning users | See the consent screen every time | Skip it when they already granted every requested scope to their personal account | | Directory listing | Not listed | Listed at [rocketverifier.com/apps](https://www.rocketverifier.com/apps/) | Every app starts unverified, including clients created through [dynamic registration](https://docs.rocketverifier.com/oauth/mcp#register-a-client). ## Submit your app for review Submit from the app's page once the listing is complete. **Step 1. Complete the listing** Open your app in [Developer apps](https://app.rocketverifier.com/dashboard/developer/apps) and fill in a description (up to 500 characters), an https logo URL, your homepage, privacy policy and terms of service URLs, and a support email. Add at least one https redirect URI. **Step 2. Trim the scopes** Turn off every scope your app does not use. Each enabled scope appears on the consent screen and in the directory listing. See [least privilege](https://docs.rocketverifier.com/oauth/scopes#request-the-least-privilege). **Step 3. Test the full flow** Connect your own account, verify an address, refresh a token, then disconnect under Settings, Connected apps and confirm your app handles `grant.revoked`. **Step 4. Click Submit for review** The status changes to In review. A reviewer approves the app, or sends it back with a note that says what to change. Fix the issues and submit again. The app keeps working throughout. Changing the name, the logo or the homepage URL of a verified app sends it back to In review and removes it from the directory until it is approved again, while existing connections keep working. ## What reviewers check Reviewers confirm that users can trust the app with their account and their credits. - **A working homepage** that describes your product and how it uses RocketVerifier. - **Public privacy policy and terms** that load without a login. The privacy policy says what you do with email addresses and verification results. - **Scopes that match features.** Every requested scope maps to a feature a reviewer can find. - **Your own name and logo.** App names cannot include "RocketVerifier", and the logo is yours rather than the RocketVerifier logo. - **No impersonation** of RocketVerifier or any company you do not represent. - **Production redirect URIs** on https, on domains you control, with leftover test URIs removed. - **A reachable support contact** for users who need help. - **Clean disconnects.** The app handles `grant.revoked` and `invalid_grant` by deleting tokens and offering to connect again. See [security best practices](https://docs.rocketverifier.com/oauth/security). ## How suspension works RocketVerifier suspends apps that misuse users' credits, misrepresent themselves or leak tokens, and a suspension stops every connection at once. - Every access token issued to the app returns `401 invalid_token`, and the token endpoint returns `invalid_client`. - The authorize URL shows users an error page instead of the consent screen. - The app leaves the directory, and you cannot edit it while it is suspended. - No `grant.revoked` webhook is sent, because the connections are paused, not deleted. Lifting the suspension restores them, and the app returns as unverified, ready to submit again. The reason appears on your app's page in Developer apps. Contact support@rocketverifier.com once the issue is fixed. Deleting an app is permanent: every connection to it ends immediately, and no `grant.revoked` webhook is sent. ## Get listed in the app directory Approved apps are listed at [rocketverifier.com/apps](https://www.rocketverifier.com/apps/), where RocketVerifier users find tools that work with their account. Each app gets its own page at `rocketverifier.com/apps/`. | Listing field | Source | | --- | --- | | Name, logo and description | Your app settings | | Website, privacy policy and terms links | Your app settings | | What the app can do | The scopes enabled on your app, in consent screen language | | Verified by RocketVerifier, with the date | Set by review | The directory is built from `GET https://api.rocketverifier.com/v1/public/apps`, a public endpoint that returns every listed app with its name, slug, description, links, scopes and `verified_at` date. ## Frequently asked questions ### Does my app stop working while it is in review? No. Your app and every existing connection keep working in review and after a rejection. The app shows the Unverified app badge until it is approved. ### What do I need before I can submit? A description, a logo URL, a homepage, a privacy policy URL, a terms of service URL, a support email and at least one https redirect URI. The Submit for review button lists anything missing. ### Which changes send a verified app back to review? Changing the name, the logo or the homepage URL. The app returns to In review and leaves the directory until it is approved again, and existing connections keep working. ### Can self-registered MCP clients be verified? No. Clients created through dynamic client registration have no owner and are never listed. Create the app in Developer apps to publish it. --- # Security best practices Source: https://docs.rocketverifier.com/oauth/security > Your app holds tokens that spend other people's credits. Send and check state, use PKCE on every request, keep the client secret on your server, store tokens encrypted, save each rotated refresh token before use with one refresh at a time per connection, and treat invalid_grant and grant.revoked as a disconnect. Go through this list before you [submit for review](https://docs.rocketverifier.com/oauth/review). Every item maps to a behavior of the RocketVerifier authorization server described in the [reference](https://docs.rocketverifier.com/oauth/reference). ## Secure the authorization flow The authorization request is where most OAuth attacks start, and four habits close them. - **Send and check `state`.** Generate at least 16 random bytes per attempt, store them in the user's session or a signed httpOnly cookie, compare them in constant time on the callback, and delete them after one use. This blocks cross-site request forgery that would connect a victim to an attacker's account. - **Use PKCE on every request.** PKCE `S256` is required for public clients and recommended for confidential ones, because it makes a stolen code useless without the verifier. Generate a new verifier for every authorization. The SDK helpers always do. - **Check `iss` on the callback.** Every redirect carries `iss=https://app.rocketverifier.com`. Reject callbacks with a different issuer if your app talks to more than one authorization server. - **Register exact redirect URIs.** Register only the URIs you use, on https and on domains you control. Never put an open redirect on your callback route. Request the fewest scopes your features need, since every scope is something an attacker gets if your storage leaks. See [least privilege](https://docs.rocketverifier.com/oauth/scopes#request-the-least-privilege). ## Protect secrets and tokens Treat the client secret like a password and tokens like the user's credit card. - **Keep the client secret on the server.** Anything in a JavaScript bundle, mobile binary, desktop app or CLI can be extracted. Register those apps as public clients with PKCE, or run the token exchange on your server. - **Rotate a leaked secret at once.** Rotating it on the app's page in [Developer apps](https://app.rocketverifier.com/dashboard/developer/apps) ends the old secret immediately and leaves existing connections untouched. - **Store tokens encrypted on the server.** Keep access and refresh tokens in your database, encrypted at rest with a key that lives outside that database. Never put them in `localStorage`, cookies readable by JavaScript, URLs or logs. - **Revoke on account deletion.** When a user deletes their account in your product or disconnects RocketVerifier from your settings page, call `/api/oauth/revoke` with the refresh token, then delete the stored tokens. ## Refresh tokens safely Refresh tokens rotate on every use and a reused token revokes the connection, so refresh must be atomic and serialized. - **Persist the rotated pair in one write.** Every refresh returns a new refresh token and retires the old one. Save the new pair before you use the new access token. A crash between the response and the write means the user connects again. - **Run one refresh at a time per connection.** Two workers that refresh the same connection at once send the same refresh token twice, and the second request revokes the whole grant. Take a lock per connection, such as a database row lock or a Redis lock, and re-read the tokens after you get it in case another worker already refreshed. - **Refresh lazily or a minute early.** Refresh on `401 invalid_token`, or proactively about 60 seconds before `expires_in` runs out. Pseudocode: ```python with lock(f"rv-refresh:{connection_id}"): tokens = db.load_tokens(connection_id) # re-read inside the lock if tokens.expires_at > now() + 60: return tokens # another worker already refreshed new = oauth.refresh(tokens.refresh_token) db.save_tokens(connection_id, new) # one write, before first use return new ``` The Node.js and Python SDKs already refresh once for concurrent calls on the same client instance and retry the original request with the same `Idempotency-Key`, so it never charges twice. Add a lock when several processes share a connection. - **Treat `invalid_grant` as disconnected.** A refresh that fails with `invalid_grant` means the user disconnected, the connection was revoked, or the refresh token expired. Do not retry. Delete the tokens and show the Connect RocketVerifier button again. ## Handle grant.revoked webhooks The `grant.revoked` webhook tells you the moment a user disconnects, so verify it and clean up. - **Verify the signature** in `X-RocketVerifier-Signature` against the raw request body with your app's webhook secret, and reject timestamps more than 5 minutes old. The SDK helpers `verifyWebhookSignature` (Node.js) and `verify_webhook_signature` (Python) do both. See [the webhook reference](https://docs.rocketverifier.com/oauth/reference#handle-the-grantrevoked-webhook). - **Make the handler idempotent.** Deduplicate on `event_id`, and make deleting tokens that are already gone a no-op. - **Answer fast.** Each event is delivered once with a 5 second timeout. Return `200` first and do slow cleanup in the background. ## Design a trustworthy connected state Clear UI keeps users confident about what your app can do on their account. - **Show which account is connected.** Call `GET /v1/me` after connecting and show the email or organization name and the credit balance, with a Disconnect button next to it. - **Explain credit errors instead of retrying.** `403 insufficient_credits` and `402 insufficient_credits` mean the connected account is out of credits. `402 api_key_spend_cap_reached` means your app reached the monthly cap the user set. Tell the user and link to [Buy credits](https://app.rocketverifier.com/dashboard/buy-credits). - **Send an `Idempotency-Key` on every write.** Retries with the same key within 24 hours return the original result without charging the user again. ## Security checklist Tick every item before you submit for review. - `state` generated per request, stored server side, compared in constant time, single use - PKCE `S256` on every authorization request - Redirect URIs registered exactly, on https, with no open redirect on the callback - Client secret only on the server, read from an environment variable - Tokens encrypted at rest on the server, never in `localStorage` - Rotated refresh token saved before use, one refresh at a time per connection - `invalid_grant` and `grant.revoked` both mark the connection as disconnected - `grant.revoked` signature verified on the raw body with a 5 minute tolerance - Fewest scopes possible, and the granted `scope` checked after the exchange - Tokens revoked when the user disconnects or deletes their account in your app - `Idempotency-Key` on every write ## Frequently asked questions ### Why did my connection get revoked when two workers refreshed? Both workers sent the same refresh token. The second request looks like a stolen token being replayed, so RocketVerifier revokes the connection. Take a lock per connection around the refresh. ### Can a single page app use Connect? Yes. Register it as a public client and use PKCE with no client secret. The OAuth endpoints allow cross-origin requests, and the client ID is safe to ship in the bundle. ### What should I do if my client secret leaks? Rotate it on your app's page in Developer apps. The old secret stops working immediately, existing connections keep working, and you deploy the new secret to your server. --- # MCP connector with OAuth Source: https://docs.rocketverifier.com/oauth/mcp > The hosted MCP server at https://api.rocketverifier.com/mcp implements the MCP authorization spec. A client discovers the issuer from protected resource metadata, registers itself with dynamic client registration, runs the authorization code flow with PKCE and resource=https://api.rocketverifier.com/mcp, and calls /mcp with the rv_at_ access token. Users only paste the URL and click Allow. This page is for developers of MCP clients, connectors and agents. To add RocketVerifier to Claude, ChatGPT, Cursor or VS Code as a user, see [Use RocketVerifier with AI assistants](https://docs.rocketverifier.com/mcp), which also lists every tool. ## How users connect Users give their AI assistant one URL and approve the connection in a browser window. **Step 1. Add the server URL** The user adds `https://api.rocketverifier.com/mcp` as a remote MCP server or custom connector. In Claude this is Settings, Connectors, Add custom connector. **Step 2. Sign in and approve** The client opens RocketVerifier. The user signs in, picks their personal account or an organization they own or administer, optionally sets a monthly credit cap, and clicks Allow. **Step 3. Use the tools** The assistant calls the tools on the user's account. The connection appears under Settings, Connected apps with the client's name and an Unverified app badge, and the user can change the cap or disconnect there at any time. ## How the authorization flow works RocketVerifier implements the full MCP authorization flow: protected resource metadata (RFC 9728), authorization server metadata (RFC 8414), dynamic client registration (RFC 7591), and the authorization code flow with PKCE `S256` and resource indicators (RFC 8707). Any client that follows the MCP specification connects with no RocketVerifier specific code. ### Discover the authorization server Call the MCP endpoint without credentials. It answers `401` with a `WWW-Authenticate` header that points to its protected resource metadata. Response 401: ```http POST https://api.rocketverifier.com/mcp HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer resource_metadata="https://api.rocketverifier.com/.well-known/oauth-protected-resource/mcp" Access-Control-Expose-Headers: WWW-Authenticate ``` GET https://api.rocketverifier.com/.well-known/oauth-protected-resource/mcp: ```json { "resource": "https://api.rocketverifier.com/mcp", "authorization_servers": ["https://app.rocketverifier.com"], "scopes_supported": [ "verify:single", "verify:bulk", "jobs:read", "jobs:write", "credits:read", "account:read", "webhooks:manage", "monitors:read", "monitors:write" ], "bearer_methods_supported": ["header"], "resource_name": "RocketVerifier MCP server", "resource_documentation": "https://docs.rocketverifier.com/mcp" } ``` Then read `https://app.rocketverifier.com/.well-known/oauth-authorization-server` for the endpoints. The full document is in the [reference](https://docs.rocketverifier.com/oauth/reference#discover-endpoints-from-metadata). ### Register a client POST JSON client metadata to the registration endpoint. It returns `201` with a `client_id`, and no dashboard account is needed. Request: ```http POST https://app.rocketverifier.com/api/oauth/register Content-Type: application/json { "client_name": "Northwind Agent", "redirect_uris": ["http://127.0.0.1:33418/callback"], "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "token_endpoint_auth_method": "none", "scope": "verify:single verify:bulk jobs:read jobs:write credits:read" } ``` Response 201: ```json { "client_id": "rvapp_7Hc2pQx9", "client_id_issued_at": 1793530800, "client_name": "Northwind Agent", "redirect_uris": ["http://127.0.0.1:33418/callback"], "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "token_endpoint_auth_method": "none", "scope": "verify:single verify:bulk jobs:read jobs:write credits:read" } ``` | Field | Rules | | --- | --- | | `redirect_uris` | Required, 1 to 10 URIs. Each is `https://`, `http://` on a loopback host (`127.0.0.1`, `[::1]`, `localhost`), or a reverse domain custom scheme such as `com.northwind.agent:/callback`. No fragments or credentials. Loopback IP redirects match on any port at authorize time. | | `token_endpoint_auth_method` | `none` (the default) creates a public client that authenticates with PKCE. `client_secret_basic` or `client_secret_post` also returns a `client_secret` with `client_secret_expires_at: 0`. | | `client_name` | 2 to 60 characters, shown on the consent screen. It cannot include "RocketVerifier". Defaults to `MCP client`. | | `scope` | Space separated scopes the client can request. Defaults to `verify:single verify:bulk jobs:read jobs:write credits:read account:read`. | | `grant_types`, `response_types` | `authorization_code` and `refresh_token`, and `code`. These are the defaults. | | `client_uri`, `logo_uri`, `policy_uri`, `tos_uri` | Optional https URLs shown on the consent screen. | Errors use the RFC 7591 format, `{"error": "...", "error_description": "..."}` with status `400`: `invalid_redirect_uri` for a bad redirect URI, and `invalid_client_metadata` for anything else. Registration is limited to 20 requests per minute per IP, so register once and reuse the `client_id`. ### Authorize with PKCE and a resource Send the user to the authorize endpoint with a PKCE challenge and the MCP resource. Request only scopes the client registered, since any other scope fails with `invalid_scope`. Authorize URL: ```text https://app.rocketverifier.com/oauth/authorize ?response_type=code &client_id=rvapp_7Hc2pQx9 &redirect_uri=http%3A%2F%2F127.0.0.1%3A33418%2Fcallback &scope=verify%3Asingle%20verify%3Abulk%20jobs%3Aread%20jobs%3Awrite%20credits%3Aread &state=STATE &code_challenge=CHALLENGE &code_challenge_method=S256 &resource=https%3A%2F%2Fapi.rocketverifier.com%2Fmcp ``` `resource` accepts `https://api.rocketverifier.com/mcp` or `https://api.rocketverifier.com`, and the token works on both the MCP server and the REST API. Self-registered clients always show the consent screen with an Unverified app badge. ### Exchange the code Public clients send their `client_id` and the PKCE verifier, with no secret. cURL: ```bash curl -X POST https://app.rocketverifier.com/api/oauth/token \ -d grant_type=authorization_code \ -d client_id=rvapp_7Hc2pQx9 \ -d code=rv_ac_Xb3k... \ -d redirect_uri=http://127.0.0.1:33418/callback \ -d code_verifier=VERIFIER ``` The response carries an `rv_at_` access token valid for 1 hour and an `rv_rt_` refresh token valid for 90 days. Refresh tokens rotate on every use, so store each new one before you use the new access token. See [rotation and reuse detection](https://docs.rocketverifier.com/oauth/reference#refresh-token-rotation-and-reuse-detection). ### Call the MCP server Send the access token as a Bearer credential on every Streamable HTTP request. Request: ```http POST https://api.rocketverifier.com/mcp Authorization: Bearer rv_at_q8Zk2N... Content-Type: application/json Accept: application/json, text/event-stream ``` An expired or revoked access token gets `401` before any tool runs, with `error="invalid_token"` added to the same `WWW-Authenticate` challenge. Refresh once and retry. If the refresh fails with `invalid_grant`, run the authorization flow again. ## Scopes each tool needs Every tool forwards to the REST API with the user's token, so the scope rules of the API apply unchanged. | Scope | Tools | | --- | --- | | `verify:single` | `verify_email`, `find_email` | | `verify:bulk` | `create_bulk_job`, `upload_bulk_from_url`, `preview_bulk_job`, `confirm_bulk_job` | | `jobs:read` | `get_job_status`, `get_job_progress`, `get_job_results`, `list_jobs` | | `jobs:write` | `cancel_job` | | `credits:read` | `check_credits` | | No scope | `check_disposable`, `mx_lookup`, `check_domain_auth` | A tool called without its scope returns an error naming the missing scope, for example `RocketVerifier API error (insufficient_scope, HTTP 403): Scope 'jobs:read' required`. The tool descriptions and costs are on the [MCP server](https://docs.rocketverifier.com/mcp#available-tools) page. ## Frequently asked questions ### Do users need an API key to use the MCP connector? No. They paste https://api.rocketverifier.com/mcp into their AI assistant, sign in to RocketVerifier and click Allow. API keys keep working as Bearer tokens for clients that prefer them. ### Do I register my MCP client in the dashboard? No. MCP clients register themselves at /api/oauth/register on first connect. Create an app in Developer apps only when you want a reviewed, listed integration. ### Which scopes does an MCP client need? verify:single, verify:bulk, jobs:read, jobs:write and credits:read cover every tool. These are the defaults a registration without a scope receives, together with account:read. ### Whose credits do MCP tool calls use? The account the user picked on the consent screen, personal or organization, with the same pricing as the API and an optional monthly cap the user sets. --- # Use RocketVerifier with AI assistants Source: https://docs.rocketverifier.com/mcp > RocketVerifier runs an official MCP server at https://api.rocketverifier.com/mcp. Add the URL to any MCP client and sign in with OAuth, or send an API key as a Bearer token. Clients that run local servers use the @rocketverifier/mcp npm package instead. Assistants then verify emails, find addresses, run bulk jobs and check domains straight from the conversation. The Model Context Protocol (MCP) lets AI assistants call external tools. With the RocketVerifier server connected, you ask in plain language and the assistant runs the verification, the bulk job or the domain check for you, on your account and your credits. ## Choose remote or local Use the remote server whenever your client supports remote MCP servers. Use the npm package for clients that only start local servers. | | Remote server | Local package | | --- | --- | --- | | Address | `https://api.rocketverifier.com/mcp` | `npx -y @rocketverifier/mcp` | | Transport | Streamable HTTP | stdio | | Sign in | OAuth in the browser, or an API key as a Bearer token | API key in `ROCKETVERIFIER_API_KEY` | | Install | None | Node.js 18 or later | | Tools | 15 | 14 (everything except `find_email`) | ## Connect Claude Claude on the web and Claude Desktop add the remote server as a custom connector and sign in with OAuth. **Step 1. Add a custom connector** Open Settings, Connectors, and choose Add custom connector. Name it RocketVerifier and enter `https://api.rocketverifier.com/mcp` as the URL. **Step 2. Sign in and approve** Click Connect. A RocketVerifier window opens: sign in, pick your personal account or an organization, optionally set a monthly credit cap, and click Allow. To run the local package in Claude Desktop instead, add it to `claude_desktop_config.json`: claude_desktop_config.json: ```json { "mcpServers": { "rocketverifier": { "command": "npx", "args": ["-y", "@rocketverifier/mcp"], "env": { "ROCKETVERIFIER_API_KEY": "rv_live_your_api_key" } } } } ``` ## Connect Claude Code Add the remote server with one command, then sign in from inside Claude Code. CLI: ```bash claude mcp add --transport http rocketverifier https://api.rocketverifier.com/mcp ``` Run `/mcp` in Claude Code, select rocketverifier and authenticate in the browser. To use an API key instead of OAuth, pass it as a header: CLI: ```bash claude mcp add --transport http rocketverifier https://api.rocketverifier.com/mcp \ --header "Authorization: Bearer $ROCKETVERIFIER_API_KEY" ``` ## Connect Cursor Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project. Cursor opens the RocketVerifier sign-in the first time it connects. .cursor/mcp.json: ```json { "mcpServers": { "rocketverifier": { "url": "https://api.rocketverifier.com/mcp" } } } ``` To use an API key, add `"headers": { "Authorization": "Bearer rv_live_your_api_key" }` next to `url`, or run the local package with `"command": "npx"`, `"args": ["-y", "@rocketverifier/mcp"]` and the key in `env`. ## Connect VS Code Add the server to `.vscode/mcp.json` in your workspace. VS Code starts the OAuth sign-in when you first use a tool. .vscode/mcp.json: ```json { "servers": { "rocketverifier": { "type": "http", "url": "https://api.rocketverifier.com/mcp" } } } ``` For the local package, let VS Code prompt for the key so it never lands in the file: .vscode/mcp.json: ```json { "inputs": [ { "type": "promptString", "id": "rv-key", "description": "RocketVerifier API key", "password": true } ], "servers": { "rocketverifier": { "type": "stdio", "command": "npx", "args": ["-y", "@rocketverifier/mcp"], "env": { "ROCKETVERIFIER_API_KEY": "${input:rv-key}" } } } } ``` ## Connect ChatGPT and other clients Any client that supports remote MCP servers connects with the URL alone, and any client that runs local servers uses the npm package. - **ChatGPT:** turn on developer mode in Settings, then create a connector with the URL `https://api.rocketverifier.com/mcp` and OAuth authentication. Sign in to RocketVerifier when prompted. - **Remote clients:** add `https://api.rocketverifier.com/mcp` as a remote or Streamable HTTP server. Clients that implement MCP authorization sign in with OAuth automatically. Others send `Authorization: Bearer rv_live_your_api_key`. - **Local clients:** run `npx -y @rocketverifier/mcp` with `ROCKETVERIFIER_API_KEY` set. `ROCKETVERIFIER_BASE_URL` overrides the API base URL, which defaults to `https://api.rocketverifier.com`. Building your own client or connector? [MCP connector with OAuth](https://docs.rocketverifier.com/oauth/mcp) covers discovery, registration and token handling. ## Choose how to authenticate The server accepts three credentials, all sent as `Authorization: Bearer`. | Credential | Prefix | Best for | | --- | --- | --- | | OAuth access token | `rv_at_` | Remote clients. The user signs in once, picks an account and can set a monthly credit cap. No key to copy or rotate. | | Live API key | `rv_live_` | Local package, scripts and clients without OAuth support. Create one in [API keys](https://app.rocketverifier.com/dashboard/api-keys). | | Sandbox API key | `rv_test_` | Testing and CI. Accepts only `@sandbox.rocketverifier.com` addresses and never charges. | OAuth connections appear under Settings, Connected apps, where you can change the cap or disconnect at any time. See [authentication](https://docs.rocketverifier.com/authentication) for API key options such as scopes, spend caps and IP allowlists. ## Available tools The remote server has 15 tools, and the npm package has the same tools except `find_email`. Every tool calls the REST API on your account, so credits, limits and results match the API exactly. | Tool | What it does | Credits | | --- | --- | --- | | `verify_email` | Verifies one address in real time: status, sub_status, score, catch-all verdict and domain details. | 1, free for unknown results and sandbox addresses | | `find_email` | Finds a person's address from their name and company domain, with a confidence and the naming pattern. Remote server only. | 1 per candidate checked with a definite answer, up to 4 | | `create_bulk_job` | Starts a bulk job from a list of up to 100,000 addresses. | 1 per unique email | | `upload_bulk_from_url` | Starts a bulk job from a CSV, TSV, TXT or XLSX file (up to 50 MB) at a public HTTPS URL. With `preview`, it waits for confirmation after a free estimate. | 1 per unique email when it starts, free with `preview` | | `preview_bulk_job` | Returns the free list health preview of a previewed job: estimated bounce rate, shares by status and credits needed. | Free | | `confirm_bulk_job` | Charges and starts a previewed job. Safe to retry: a job is never charged twice. | 1 per unique email | | `get_job_status` | Returns a bulk job's status and summary counts. | Free | | `get_job_progress` | Returns poll-friendly progress: processed, remaining, percent, counts, rate and ETA. | Free | | `get_job_results` | Returns paginated per-email results, filterable by classification. | Free | | `list_jobs` | Lists recent bulk jobs, filterable by status. | Free | | `cancel_job` | Cancels a pending or running job and refunds unused credits. | Free | | `check_credits` | Returns the credit balance and usage today and this month. | Free | | `check_disposable` | Checks whether an email's domain is a disposable provider. | Free | | `mx_lookup` | Looks up a domain's MX records. | Free | | `check_domain_auth` | Scores a domain's SPF, DMARC and DKIM setup from 0 to 100, with fix recommendations. | Free | Unknown results in bulk jobs are refunded when the job completes. Tool arguments are snake_case on the remote server (`job_id`, `source_url`) and camelCase in the npm package (`jobId`, `sourceUrl`). Your assistant reads the schema, so this matters only when you call tools directly. Each tool maps to an endpoint in the [API reference](https://docs.rocketverifier.com/api), and OAuth connections need the [scope for each tool](https://docs.rocketverifier.com/oauth/mcp#scopes-each-tool-needs). ## Example prompts Ask in plain language. The assistant picks the tool and explains the result. - "Is maya@northwind.io deliverable?" - "Find the email address for Maya Chen at northwind.io." - "Check whether mailinator.com is a disposable email provider." - "Run a domain authentication check on northwind.io and tell me which DNS records I'm missing." - "Preview the list at https://files.northwind.io/leads.csv and tell me the estimated bounce rate before I spend credits." - "Verify these 200 addresses in bulk and summarize how many are risky." - "How many RocketVerifier credits do I have left?" ## Test without spending credits Sandbox addresses return fixed results for free on any credential, so you can try `verify_email` before you spend a credit. Ask the assistant to verify `deliverable@sandbox.rocketverifier.com` or `undeliverable@sandbox.rocketverifier.com`. The full list of sandbox addresses is on [verify an email](https://docs.rocketverifier.com/api/verify#try-it). For CI and shared demos, connect the local package with an `rv_test_` sandbox key, which refuses every non-sandbox address. ## Frequently asked questions ### Do I need an API key? Not for the remote server. Add https://api.rocketverifier.com/mcp and sign in to RocketVerifier when your client asks. The local @rocketverifier/mcp package reads an API key from ROCKETVERIFIER_API_KEY. ### How much do the tools cost? The same as the API. verify_email costs 1 credit, bulk jobs cost 1 credit per unique email, find_email costs up to 4 credits, and status, results, credit and domain tools are free. Unknown results are free. ### Can I try it without spending credits? Yes. Ask the assistant to verify addresses at @sandbox.rocketverifier.com, such as deliverable@sandbox.rocketverifier.com. They return fixed results for free. A sandbox key (rv_test_) restricts the server to those addresses. ### Will the assistant spend credits without asking? The bulk tools are built for a preview first. upload_bulk_from_url with preview returns a free bounce estimate, and confirm_bulk_job, the step that charges, tells the assistant to confirm with you before it runs. ### Which is better, the remote server or the npm package? The remote server needs no install, supports OAuth sign-in and has all 15 tools. Use the npm package for clients that only run local stdio servers. --- # Docs for AI assistants Source: https://docs.rocketverifier.com/ai > Every page of these docs is available as Markdown by adding .md to its URL (/index.md for the home page). /llms.txt indexes every page, /llms-full.txt holds the whole site in one file, /openapi.yaml is the API spec, and /build-an-integration.md is a self-contained spec for building an OAuth integration. Each page also has Copy page and Open in Claude buttons. These docs are written to be read by people and by AI assistants. Point your assistant at the right file and it answers with current endpoints, fields and error codes instead of guesses. ## Machine-readable files Each format serves a different job, and all of them are generated from the same source as the pages you are reading. | File | What it holds | Use it for | | --- | --- | --- | | [/llms.txt](https://docs.rocketverifier.com/llms.txt) | An index of every page with its one-line description and Markdown URL, following llmstxt.org | Letting an assistant pick the pages it needs | | [/llms-full.txt](https://docs.rocketverifier.com/llms-full.txt) | Every page in reading order, in one Markdown file | Broad questions and loading the whole site into context | | `.md` | A Markdown copy of any page | Focused tasks such as one endpoint or one integration | | [/openapi.yaml](https://docs.rocketverifier.com/openapi.yaml) | The OpenAPI 3 specification of the REST API | Generating clients, typed models and tool definitions | | [/build-an-integration.md](https://docs.rocketverifier.com/build-an-integration.md) | A self-contained spec for building a Connect RocketVerifier (OAuth) integration | Asking a coding assistant to add Connect to your app | ## Get any page as Markdown Add `.md` to any docs URL to get the page as clean Markdown, with code samples and tables intact. - `https://docs.rocketverifier.com/api/verify` becomes `https://docs.rocketverifier.com/api/verify.md` - The home page is `https://docs.rocketverifier.com/index.md` cURL: ```bash curl https://docs.rocketverifier.com/oauth/quickstart.md ``` ## Use the page buttons Every page has four buttons under its title that hand the page to an assistant in one click. - **Copy page** copies the page's Markdown to your clipboard, ready to paste into any chat. - **View as Markdown** opens the `.md` version. - **Open in Claude** and **Open in ChatGPT** start a new chat that reads the page's `.md` URL, so you can ask questions or build from it straight away. ## Prompt your coding assistant Name the file in your prompt and say what you are building. These prompts work in Claude Code, Cursor, Copilot and other coding assistants. Verify signups: ```text Read https://docs.rocketverifier.com/api/verify.md and add server-side email verification to my signup endpoint. Reject undeliverable addresses and show did_you_mean suggestions. ``` Add Connect RocketVerifier: ```text Read https://docs.rocketverifier.com/build-an-integration.md and add a Connect RocketVerifier button to my app so users can verify their contacts. ``` Generate a client: ```text Use https://docs.rocketverifier.com/openapi.yaml to generate a typed client for the bulk verification endpoints. ``` ## Let assistants call the API Reading docs teaches an assistant how RocketVerifier works, and the MCP server lets it act. Connect `https://api.rocketverifier.com/mcp` and the assistant verifies emails, runs bulk jobs and checks domains on your account. See [Use RocketVerifier with AI assistants](https://docs.rocketverifier.com/mcp). ## Frequently asked questions ### Which file should I give my coding assistant? For a specific task, the .md URL of the relevant page. For broad questions, /llms-full.txt. For adding Connect RocketVerifier to an app, /build-an-integration.md. ### Are the Markdown files kept in sync with the site? Yes. The Markdown, llms.txt and llms-full.txt are generated from the same source files as the HTML pages on every deploy. ### How do I let an assistant call the API instead of just reading about it? Connect the RocketVerifier MCP server at https://api.rocketverifier.com/mcp. The assistant can then verify emails and run bulk jobs on your account. ---