Sandboxes

One trap with two ways in. Everything you capture belongs to a sandbox, so this is the first thing you make.

What you get

A sandbox is minted with a random id and a secret, and those two values are the whole of its interface:

smtpUsername — the id. Authenticates your mailer, and is the capture subdomain. Not secret.
smtpPassword — the secret, the other half of the SMTP credential. This is the only one worth protecting.
captureUrl — https://<sandbox-id>.trapit.dev. Any path, any method. Not secret.

The id doing double duty is deliberate: one string identifies the sandbox on both ingresses, so there is no second identifier to look up or keep in step. It is not secret — it appears in webhook URLs, DNS queries and proxy logs — and nothing authorises on it alone.

Creating one

In the dashboard

Hit + in the rail, give it a name, and you land on its page with the credentials and capture URL ready to copy. The name is for you: nothing routes on it, so two sandboxes may share one.

Over the API

curl https://trapit.dev/api/v1/sandboxes \
  -H "Authorization: Bearer trap_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "checkout-staging"}'

The 201 carries everything needed to send it traffic — smtpHost, smtpPort, smtpUsername, smtpPassword and captureUrl — so a CI job can create and configure in one step.

From an agent

create_sandbox over MCP returns the same thing, which is what lets an agent set up its own trap mid-task. MCP tools →

How many, and how long

Two shapes cover almost everything:

One per app and environment — checkout-staging, billing-qa — living as long as the environment does. Tag them Application and Environment so the list stays readable.
One per test run, ephemeral — created with "ephemeral": true, expiring on a TTL of 1 to 1440 minutes (default 60) and taking everything it captured with it. No cleanup step to forget.

A sandbox per run is how you isolate parallel CI. Two runs with their own sandboxes share nothing — not a mailbox, not an address convention both have to honour — so neither can see the other's traffic no matter what addresses their fixtures generate.

The secret

It stays viewable. Open the sandbox any time and reveal it — unlike an API key, which is shown once and stored only as a hash.

The difference is what each one can do. An API key reads and deletes everything in your workspace. A sandbox secret only lets someone write traffic into one throwaway trap: it cannot read a captured message, delete anything, or reach another sandbox. It also gets pasted into several environments over its life, and a show-once secret would mean rotating it constantly — which is exactly when credentials end up written down somewhere worse.

Deleting

Deleting a sandbox takes both capture streams with it. Clearing is narrower: emptying the email side never discards captured requests, and the reverse.

Email capture → · HTTP capture →