Skip to content
RocketVerifierDOCS

Get started

Sandbox and testing

In short

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.

On this page

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.

Addressstatussub_statusscore
deliverable@sandbox.rocketverifier.comdeliverablenone95
valid@sandbox.rocketverifier.comdeliverablenone98
undeliverable@sandbox.rocketverifier.comundeliverablemailbox_not_found0
invalid@sandbox.rocketverifier.comundeliverablemailbox_not_found0
disposable@sandbox.rocketverifier.comundeliverabledisposable10
risky@sandbox.rocketverifier.comriskycatch_all45
admin@sandbox.rocketverifier.comriskyrole_based60
unknown@sandbox.rocketverifier.comunknownsmtp_unavailable30

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.

Sandbox addresses return fixed results from the live API. No key, no credits.

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
curl -X POST https://api.rocketverifier.com/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "undeliverable@sandbox.rocketverifier.com"}'
Response 200 (excerpt)
{
  "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 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 by ticking Sandbox key (rv_test_...). It takes the same permissions, expiry date and IP allowlist as a live key.

EndpointWith an rv_test_ key
POST /v1/verifySandbox addresses only. Any other address returns 403 sandbox_key_restricted.
POST /v1/verify/bulkJobs 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/uploadNot available. Returns 403 sandbox_key_restricted; use POST /v1/verify/bulk with sandbox addresses.
POST /v1/finderDomain sandbox.rocketverifier.com only, with a fixed found result.
Read endpoints (jobs, credits, webhooks, monitors)Work as usual.
403 sandbox_key_restricted
{
  "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.

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"

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.

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.

  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.

  2. Assert on fixed results

    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");
      });
    });
  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 like any other.

Next steps#

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.

Updated 11 November 2026Suggest an edit