Sandbox Testing

What sandbox testing does

A sandbox workspace is a test-only child workspace. It accepts the same transactional API and SMTP inputs as a live workspace, stores a preview of the content in Simply Send, and produces deterministic lifecycle events. No email is sent to an external mailbox.

Set up a sandbox

1. Open Account → Workspaces.
2. Click New Workspace.
3. Fill in the new workspace form:
   • Workspace Type: Sandbox.
   • Parent Workspace: an active, paid Live workspace.
   • Workspace Name: a name for your test workspace.
   • Workspace Email: the contact email for this workspace.
4. Click Create Workspace.
5. Stay in the Live parent workspace. Open the Email Credits tab. Choose the Sandbox and transfer credits to it. This gives the Sandbox workspace credits to send test emails.
6. Go back to the Workspaces view. Click the Sandbox workspace you created.
7. After switching to the Sandbox workspace, open Domains.
8. Add a strict test subdomain (e.g. test.example.com) under a verified domain (e.g. example.com) in the direct Live parent workspace. It is verified right away. Do not add DNS records.
9. Open Compliance Templates. Create an Unsubscribe template and a Company Address template with valid HTML. They are approved right away.
10. Create an API key or SMTP credentials. Use them as usual.
11. Send only to an allowed test email from the table below.

Allowed test email addresses

This fixed list is the sandbox test-data allow list; it is not configurable. Each address produces a fixed outcome. You may include multiple supported addresses in one request to test separate recipient outcomes; each recipient receives its own simulated record and message ID.

Test through the API

Send the same request shape you use in live. Substitute the sandbox workspace ID and a sandbox API key. The example uses the Transactional API endpoint, https://tapi.simplysend.email/send. Marketing sandbox sends use https://mapi.simplysend.email/send with a Marketing API key and retain the normal Marketing response fields, including jobId. The API returns immediately after the simulated send is accepted; lifecycle events are processed asynchronously.

A successful response is marked status: "simulated", simulated: true, and environment: "sandbox". It lists the recipient, role, message ID, and selected outcome.

Test through SMTP

Use smtp.simplysend.email with the sandbox workspace credentials. SMTP accepts the message immediately when simulation succeeds; inspect the sandbox workspace for the asynchronous event sequence.

Use the same SMTP setup as a live workspace: STARTTLS on port 587 or SSL/TLS on port 465. See the SMTP Relay guide for client-specific examples.

Verify events, webhooks, and workflows

Limits and retention

• Rate limit: a sandbox workspace can accept up to 10 API or SMTP sends per minute. Exceeding the limit returns HTTP 429 with SANDBOX_RATE_LIMITED; retry after the minute window resets.
• Five-day lifecycle: sandbox email content, stored previews, email records, event history, and related analytics expire after five days. Cleanup is asynchronous, so do not rely on a record being removed at an exact clock time.
• No external delivery: addresses outside the simulation list are rejected rather than delivered. Do not use sandbox to test a customer inbox, real recipient engagement, inbound replies, or unsubscribe links.
• Credits: a sandbox has no separate subscription fee, but each simulated recipient uses the sandbox workspace's email balance at the applicable Transactional or Marketing rate. A billing owner can transfer credits to the sandbox from its parent workspace before testing.

Recommended integration test plan

1. Send to deliver@simplysend.email; assert the accepted response, Send event, Delivery event, dashboard status, and webhook marker.
2. Send to hard-bounce@simplysend.email and soft-bounce@simplysend.email; verify your permanent and retryable bounce paths remain distinct.
3. Send to complain@simplysend.email; verify Delivery followed by Complaint handling without changing a real recipient's status.
4. Send to delay@simplysend.email; verify event ordering and that delivery is not assumed before the final Delivery event.
5. Send to open@simplysend.email or click@simplysend.email; verify the Open and Click event paths.
6. Send to an unsupported address such as customer@example.com; assert the recipient guard error.
7. Send more than 10 requests within a minute; assert your client backs off after the rate-limit response.
8. Repeat one request with the same idempotency key; verify your application treats the retry as the same logical send.