# Sandbox

> Test keys send to scripted numbers: delivered, busy then delivered, partial, no answer, unknown, provider timeout, invalid number. Same events, no cost.

Page: https://faxforagents.com/docs/sandbox/
Last changed: 2026-10-28

Updated Oct 28, 2026

A test key (`ffa_test_...`) sends only to the sandbox. No carrier, no cost, nothing leaves the box. The outcome is decided by the destination number or by a scenario you select. Every state a real fax can end in can be rehearsed, including the ones you hope never to see.

## Destinations

Scripted sandbox destinations

| Destination | Scenario | What happens |
| --- | --- | --- |
| `+15550000001` | `delivered` | every page on the first attempt, evidence on the attempt |
| `+15550000002` | `busy_then_delivered` | busy on attempt 1, delivered on attempt 2 |
| `+15550000003` | `partial` | the call drops after 3 pages (N minus 1 on a short fax). Those pages charged, the rest released |
| `+15550000004` | `no_answer` | nobody answers on any of the 3 bounded attempts. failed, failure_code no_answer |
| `+15550000005` | `unknown` | the provider accepts the fax and never reports. unknown after the deadline, failure_code callback_missing, hold kept |
| `+15550000006` | `provider_timeout` | the provider does not answer the send call. unknown, failure_code provider_timeout |
| `+15550000007` | `invalid_number` | rejected at once. failed, no retry |
| `any other +1 number` | `delivered` | the default |

A number outside `+1` on one of the [published routes](https://faxforagents.com/pricing/) is quoted and delivered the same way, at $0 on the sandbox. A number on no route, or on an excluded one, is refused with `unsupported_destination`.

## How do I select a scenario?

Shell

```
`curl -s $FFA/sandbox/scenarios -H "Authorization: Bearer $FFA_KEY" \ -H "Content-Type: application/json" \ -d '{"scenario": "partial", "destination": "+12025550100"}'`
```

That destination behaves that way for 24 hours. Without `destination` it applies to every send of the organization that has no more specific fixture. `GET /v1/sandbox/scenarios` lists the catalog, the table above and the active fixtures. With the CLI: `ffa sandbox scenario partial --to +12025550100`. A live key is refused on these routes with `sandbox_only`.

## How fast is the sandbox, and what does it cost?

The sandbox answers the send call at once, so one worker pass takes a job from `queued` to its outcome. Retries are scheduled after 60 seconds and the unknown deadline is 600 seconds, as in production. Sandbox pages cost $0.000. Every test organization starts with a seeded wallet of $100.00 test credit. The hold, capture and release path runs exactly as it will with real money. `GET /v1/balance` with a test API key shows that wallet.

## Inbound and reset

`POST /v1/sandbox/inbound-faxes` creates a synthetic inbox item and a `fax.received` event with the live shape. `DELETE /v1/sandbox/data` removes the organization's test faxes, attempts, events, deliveries, quotes, documents, uploads, synthetic inbox items and fixtures. It brings the test wallet back to the seed with one balancing ledger entry.

## Webhooks

Sandbox sends fire the same events with the same signatures as live ones: `fax.queued`, `fax.started`, `fax.delivered`, `fax.partially_delivered`, `fax.failed`, `fax.outcome_unknown`. A receiver can be finished end to end before the first live page.