Sandbox Mode

Test your integration safely without sending real emails or affecting production data.

What is sandbox mode?

Sandbox mode lets you develop and test against the TopMail API without triggering real email sends. All other API operations (contacts, lists, campaigns, templates) work normally against your live workspace data, but email send calls return simulated success responses instead of actually delivering messages.

Creating sandbox keys

To create a sandbox API key:

Go to your workspace settings.
Navigate to the API Keys tab.
Click "Create API Key" and select Sandbox as the key type.

Sandbox keys use the prefix tm_test_, while live keys use tm_live_.

Sandbox behavior

Feature	Sandbox Behavior
Email sends	Returns mock success with simulated message IDs. No emails delivered.
Contacts, Lists, Templates	Full read/write access to your live workspace data.
Rate limits	Same rate limits as live keys.
Domain validation	Skipped in sandbox. No verified domain needed.
Suppression checks	Skipped in sandbox. All recipients accepted.

Example sandbox request

The request is identical to a live send, but uses a sandbox key:

curl -X POST https://api.topmail.so/api/v1/email/send \
  -H "Authorization: Bearer tm_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "test@example.com",
    "subject": "Test email",
    "html": "<p>This will not actually be delivered.</p>",
    "from_email": "you@yourdomain.com"
  }'

{
  "data": {
    "sent": 1,
    "failed": 0,
    "skipped": 0,
    "total": 1,
    "results": [
      {
        "to": "test@example.com",
        "message_id": "sandbox_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "success": true
      }
    ],
    "sandbox": true
  }
}

Notice the sandbox: true field and the sandbox_ prefix on message IDs in the response. These help you confirm you are in sandbox mode.