Sandbox mode

Every new email service starts in sandbox mode. It’s a safe playground that:

• Lets you call the real POST /emails endpoint with the real API and the real response shape.
• Delivers email only to recipients you have explicitly verified inside the service.
• Uses a shared sandbox From: address (onboarding@runsite.app) — your real domain doesn’t need to exist yet.
• Has a small daily send cap (a few dozen messages) to discourage misuse.

You stay in sandbox mode until you verify a sending domain on the service. After that, the service automatically flips to Production.

Why sandbox exists

Without sandbox, the very first time you wire up email in a new project you’d have to:

• Pick a domain.
• Set up DNS at your registrar.
• Wait for verification.
• Only then see your code work end to end.

With sandbox you skip all of that for development — type to: ["you@yourcompany.com"], send, and the email lands in your inbox right away. Real DNS comes later, when you’re ready.

The verified-recipients list

Inside a sandbox service the Overview tab shows the verified recipients. Each row is an email address that has clicked through the verification code Runsite sent.

When you create a service the dashboard offers to pre-add your own login email — that’s why the very first sandbox to: usually just works.

Adding a recipient

1. Email service → Overview → Add Verified Email.
2. Enter the address (e.g. your colleague’s, or a different inbox of yours).
3. Runsite sends a 6-digit verification code to that address — valid for 24 hours.
4. The recipient (or you) opens the email and types the code into the modal.
5. Once confirmed, the address appears in the list and can receive sandbox messages.

Recipients you haven’t verified are rejected with a clear 400 error:

{
  "error": "'someone@external.com' is not a verified sandbox recipient. Add and verify it in the Email Service sandbox settings."
}

That makes sandbox safe to call from any test environment — you cannot accidentally email real users.

Removing a recipient

Click the trash icon next to the address. They stop receiving sandbox mail immediately.

Sandbox From:

While the service is in sandbox mode the From: you put in the request is rewritten to the shared sandbox sender, with your original from preserved as Reply-To: so replies still come back to you:

From:     Runway Email <onboarding@runsite.app>
Reply-To: hello@yourcompany.com

This is what makes sandbox safe — you cannot use it to fake a From: address on a domain you don’t own.

Daily limit

Sandbox traffic is rate-limited to a low daily cap (~50 messages per service per day by default). The cap exists to keep sandbox what it is: a development tool, not a back door for production sending.

If you hit it, the API returns 429 Too Many Requests. Wait for the next day, or — better — verify a sending domain and switch to production.

What still works exactly like production

• The endpoint, headers, request body and response body are identical.
• API keys are the same rs_eml_… keys.
• Email status, stats and webhooks fire the same way (you’ll see delivered, bounced etc. for sandbox traffic too).
• HTML, plain text, custom headers and replies all behave the same.

That means the code you ship to production is the code you’ve already tested in sandbox — you don’t change a line, only the API key and the domain.

Going to production

When you’re ready:

1. Add a sending domain on the Domains tab.
2. Add the SPF / DKIM / DMARC records the dashboard gives you.
3. Click Verify.

Once any one domain is verified, the service header flips from yellow Sandbox to green Production. From that moment:

• The verified-recipient gate is dropped — you can email anyone.
• Your real From: address is used (and signed) — receivers see your domain.
• The daily cap is lifted to your production quota.

Fallback behavior in production

Even after the service is in production, if you accidentally from a domain that isn’t verified on this service, Runsite falls back to the sandbox sender instead of refusing the request. The response includes mode: "sandbox_fallback" and a reason, so you can spot misconfiguration in your logs without losing the message:

{
  "id": "…",
  "status": "sent",
  "mode": "sandbox_fallback",
  "from": "noreply@yourcompany.com",
  "message": "Email sent via sandbox: domain 'yourcompany.com' is not registered for this email service"
}

Treat sandbox like a real environment

Use a separate email service (and therefore separate API keys) for development and production. Sandbox is a great fit for the dev service, production is a great fit for the prod service. Don’t share a key between environments — when you rotate prod, you don’t want dev to break.