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