The production sandbox
Mailroom's sandbox runs on production itself. A mk_test_ key executes the real code path against the real host and returns simulated quotes, labels, tracking and voids — no carrier calls, no charges, no separate base URL to configure and later forget to change.
Last updated
Why it runs on production
Most shipping APIs give you a second hostname. That creates the failure everyone knows: an integration that passes every test against the sandbox and breaks on the first real request, because the environments drifted — or because a base URL never got switched and the first live shipment quietly went to the test host.
Mailroom removes the variable. There is one host and one code path. The keydecides whether the work is real. A mk_test_ key runs in synthetic mode; a mk_live_ key hits carriers. Promoting an integration means swapping a credential, not re-pointing a client.
What synthetic mode actually does
- Quotes, labels, tracking and voids are simulated end to end, with deterministic and realistic prices.
- Zero carrier calls and zero charges — nothing reaches UPS, FedEx or USPS.
- Every response carries
"synthetic": true, so an agent can assert it is not live. - Labels are watermarked and not shippable.
- No card, no balance, and no human approval needed to start.
Testing the failure paths
Happy paths are the easy half. Two magic values in line1 let an agent exercise address failures deliberately, so error handling gets tested before it matters.
| Address line1 contains | Result |
|---|---|
AMBIGUOUS | Returns a candidate list — the agent must choose or ask a human. |
INVALID | Rejection — exercises the address_validation_failed path. |
Getting a test key
One call. No human approval, no card, no sales conversation. The signup does require the name, email and phone of a reachable human contact — deliberately, so no autonomous account is a black box.
curl -X POST https://app.mailroom.software/api/v1/signups \
-H "Content-Type: application/json" \
-d '{ "companyName": "Acme Robotics",
"email": "ops@acme-robotics.com",
"contactName": "Dana Smith",
"contactPhone": "+1 555 010 4477",
"termsAccepted": true }'
# → organization + mk_test_ key in the response. Usable immediately.Going live
Three steps, with a human in the money loop throughout: the agent requests a billing setup link and hands the URL to its human admin, who adds a card and signs the billing authorization — card details never pass through the API. The agent tops up the prepaid balance, then calls activate_live_key. If anything is missing, the API returns a 402 that itemizes exactly which prerequisites remain rather than failing vaguely.
What a live key may then spend is a separate question, answered on spending caps and human control.