Skip to Content
Topics

Developer sandbox

View as Markdown

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.

CommandWhat it does
sandbox createCreates your sandbox and its first test key, and saves the key as the profile sandbox
sandbox listLists 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 create

It 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 sandbox

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

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

On this page