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.
| 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.
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 -X POST https://api.rocketverifier.com/v1/verify \
-H "Content-Type: application/json" \
-d '{"email": "undeliverable@sandbox.rocketverifier.com"}'{
"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.
| 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. |
{
"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"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.
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.
Create a sandbox key for CI
Create an
rv_test_key named after the pipeline, and store it as a secret such asROCKETVERIFIER_TEST_KEY. Give it only the permissions your tests use.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"); }); });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"Cover the unknown path
unknown@sandbox.rocketverifier.comreturnsunknownwithsub_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