Testing and the sandbox Coming soon
The plan for testing sends and incoming mail without real customers: test keys, a sandbox workspace and magic addresses. Coming soon.
Coming soon. Nothing on this page works yet. It's the design for the sandbox, shared early so you can plan your tests around it. Tell us what you'd need at hello@userookery.com.
Today, the safe way to try the API is a read-only key, and drafts instead of sends: see the quickstart and Draft, don't send. Try it in the reference never sends. The sandbox will let you test the rest, including sending and receiving, without a real customer ever seeing it.
Test keys and a sandbox workspace
- Every workspace gets a sandbox: a separate copy with its own inboxes, conversations and documents, and none of your real mail.
- Test keys start with
rk_test_and only work in the sandbox. Live keys will start withrk_live_; therk_keys you have now keep working as live keys. - The same endpoints, the same MCP server and the same rules apply. Only the key decides which workspace you're in.
- Nothing sent from the sandbox leaves Rookery. Mail to real addresses is stopped and shown in the outbox inspector instead.
The outbox inspector
Sandbox → Outbox shows every email the sandbox would have sent: who it was to, the exact text and HTML, its attachments, and what happened to it (delivered, bounced, delayed). You can open each one as the recipient would see it.
Magic recipient addresses
Send to any address at these domains, in the sandbox, to get a predictable result. They're on .test, a domain name that's reserved and can never reach a real inbox.
| Send to an address at | What happens |
|---|---|
delivered.rookery.test | Delivered |
bounce.rookery.test | A hard bounce: the reply shows as failed, with the reason |
delay.rookery.test | Delivered after 2 minutes |
reply.rookery.test | Delivered, then a reply arrives about 30 seconds later |
ooo.rookery.test | An out-of-office reply arrives |
secure.rookery.test | The recipient opens the secure link and replies through it |
For example, a reply to lee@reply.rookery.test goes out, and Lee writes back half a minute later, in the same conversation.
Simulate incoming mail
POST /v1/sandbox/inbound delivers an email to a sandbox inbox through the real pipeline: Scout sorts it, checks it for scams and lets it in (or holds it), and Quill and Fetch do what they'd do with real mail. Send either:
- JSON:
from,to,subject,text, and optionalhtml,cc,inReplyToand attachments; or - raw MIME: the whole message, with
Content-Type: message/rfc822.
In the app, Sandbox → Simulate an email offers ready-made scenarios: a customer asking about an order, an invoice with a PDF, a phishing attempt, a reply to a thread, a newsletter.
Webhooks in the sandbox
Sandbox events go to the same webhooks as live ones, with livemode: false, so your code can tell them apart and test both paths.
Predictable helpers for CI
In the sandbox, the helpers can be set to give the same answer every time, so tests don't depend on an AI model's mood:
- Scout sorts by simple rules you can read, like a subject starting with
[urgent]; - Quill drafts a fixed reply that names the conversation;
- Fetch's document checks pass or fail by file name.
That way a test like "a new email arrives, the agent drafts a reply, the draft waits for a yes" passes or fails for real reasons.