Developer sandbox
A developer sandbox is a Kenso workspace of your own for building and testing an integration. It starts with example campaigns, contacts, inboxes and conversation threads, and everything in it is simulated: sends, orders and charges never reach a provider. Nothing leaves Kenso. Campaigns still plan and send in the sandbox, your webhook endpoints still receive its events, and a few reserved test addresses answer like real leads would.
You work in it with a test key: kenso_test_ and 49 letters and digits. A test key works only in its sandbox, and only on Ken-Version: 1.1 routes, which is what kenso sends: every other workspace answers 404, and a request without that version, or to a route that has no 1.1 form, answers 403. You have one sandbox at most.
This is not the cloud sandbox a coding agent runs in (kenso work run, see kenso docs agents).
Sandboxes are in beta: the commands work in workspaces where Kenso has turned them on.
Commands
The sandbox commands run with your live key, in your current workspace. Run with a test key, they stop before sending anything.
| Command | What it does |
|---|---|
sandbox create | Creates your sandbox and its first test key, and saves the key as the profile sandbox |
sandbox list | Lists your sandbox |
sandbox reset [sandboxId] | Deletes everything in the sandbox and seeds it again. Test keys and webhook endpoints stay |
sandbox key [sandboxId] | Creates another test key (5 active at most) and saves it as the profile sandbox |
sandbox delete [sandboxId] | Deletes the sandbox with its webhook endpoints and their delivery history, and revokes its test keys, then removes the profile sandbox |
Without an id, reset, key and delete use your one sandbox. delete asks first on a terminal; in a script or an agent it needs --yes, and --dry-run prints the request it would send.
Quick start
kenso sandbox createIt prints the sandbox and its test key once, as JSON:
{"sandboxId":20417,"name":"Sandbox ([email protected])","status":"ready","seed":{"campaigns":2,"contacts":25,"inboxes":2,"threads":4},"testKey":{"id":"apk_...","prefix":"kenso_test_AbCdE","secret":"kenso_test_...","expiresAt":"2027-02-13T18:00:00Z"},"profile":"sandbox"}The key is saved as the profile sandbox, and your active profile stays the live one. Add --profile sandbox to run any command in the sandbox:
kenso campaigns list --profile sandbox
kenso auth status --profile sandboxKENSO_API_KEY and KENSO_WORKSPACE_ID win over every profile, --profile sandbox included: while either is set, a command does not use the test key and its sandbox. Unset them, or set KENSO_API_KEY=<the test key> KENSO_WORKSPACE_ID=<sandboxId> to work in the sandbox. sandbox create and sandbox key warn when they are set, and auth status when they override the profile.
auth status says "keyKind":"test" and names the sandbox. A test key expires after 90 days: kenso sandbox key makes a new one and saves it over the old one in the profile. To start over, kenso sandbox reset. When you are done, kenso sandbox delete --yes.
Your code can use the same key without the CLI: send it as Authorization: Bearer <key> and the sandbox id as X-Ken-Workspace-Id.
Reserved test leads
Add a lead with one of these addresses to a sandbox campaign and launch it. After its simulated send, the lead gets that outcome. A +label before the @ is ignored, so [email protected] works too.
| Address | Outcome in a sandbox |
|---|---|
[email protected] | A reply classified Interested |
[email protected] | A hard bounce |
[email protected] | An out-of-office auto reply |
[email protected] | An unsubscribe |
Any other address gets a simulated send and nothing after it.