Sandbox Testing

Test your integration end to end without consuming credits.

How It Works

Sandbox mode is activated by the API key, not by special email addresses. Create a test API key in your dashboard (Dashboard → API → Create API Key → Test (Sandbox)). Test keys start with cb_test_ and:

• return deterministic mock results — no real verification is performed,
• never consume credits (they work even at a zero balance),
• are accepted only by POST /api/v1/verify and GET /api/v1/credits — any other endpoint responds 403,
• mark every response with "sandbox": true so mock data can never be mistaken for real results.

Live keys (cb_live_) always perform real verifications and never return mock data. The two modes cannot mix.

Choosing the Result

The local part of the submitted address selects the mock outcome. Any domain works. Unrecognized local parts return deliverable.

Deliverable

Local part	Result
(anything else)	deliverable, reason accepted_email, score 95
deliverable@ / valid@	deliverable, reason accepted_email, score 95
free@	deliverable with isFreeProvider: true
typo@	deliverable with a hasTypo suggestion

Undeliverable

Local part	Result
undeliverable@ / invalid@ / rejected-email@	undeliverable, reason rejected_email
invalid-domain@ / nomx@	undeliverable, reason invalid_domain, mxRecords: false
invalid-syntax@ / syntax-error@	undeliverable, reason invalid_syntax
fullmailbox@	undeliverable with account.fullMailbox: true
disabled@	undeliverable with account.disabled: true

Risky

Local part	Result
risky@ / low-quality@	risky, reason low_quality
catch-all@ / catchall@ / accept-all@	risky, reason low_deliverability, isCatchAll: true
disposable@	risky with isDisposable: true
role@ / rolebased@	risky with isRoleBased: true

Unknown

Local part	Result
unknown@	unknown, reason unknown
timeout@	unknown, reason unavailable_smtp

Error Simulation

Local part	Result
insufficient-credits@	HTTP 402 with code INSUFFICIENT_CREDITS

Plus-Tags

Keywords also work as plus-tags, so you can keep a realistic address shape:

jane.doe+risky@example.com   → risky
jane.doe+undeliverable@example.com → undeliverable

Example Test Request

curl -X POST https://api.clearbounce.net/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cb_test_YOUR_TEST_KEY" \
  -d '{"email": "undeliverable@example.com"}'

Response (abbreviated):

{
  "success": true,
  "sandbox": true,
  "data": {
    "email": "undeliverable@example.com",
    "status": "undeliverable",
    "reason": "rejected_email",
    "score": 0,
    "isDeliverable": false
  },
  "creditsRemaining": 5000
}

creditsRemaining reflects your real balance — sandbox calls never change it.

Going Live

Switch the X-API-Key header to a live key (cb_live_). No other change is needed: request and response shapes are identical, minus the "sandbox": true flag.