Sandbox Mode
Test API integrations without sending real emails using sandbox mode
Sandbox Mode
Sandbox mode intercepts outbound emails and stores them in a sandbox inbox instead of delivering them via SMTP. Use it during development and integration testing to verify payloads without sending real messages.
Enabling Sandbox Mode
Add the X-MisarMail-Sandbox: true header to any send request:
curl -X POST https://mail.misar.io/api/v1/send \
-H "Authorization: Bearer msk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "X-MisarMail-Sandbox: true" \
-d '{
"from": { "email": "hello@yourdomain.com" },
"to": [{ "email": "test@example.com" }],
"subject": "Test Email",
"html": "<p>Hello from sandbox!</p>"
}'The request is validated and processed identically to a real send — quota checks, merge tags, and template rendering all run — but no SMTP delivery occurs.
Response (same as a real send, with sandbox: true):
{
"success": true,
"message_id": "sb_msg_abc123",
"sandbox": true
}Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/sandbox | List recent sandbox sends |
DELETE | /api/v1/sandbox | Clear sandbox send history |
GET /api/v1/sandbox
Returns sandbox sends from the last 7 days, newest first.
curl "https://mail.misar.io/api/v1/sandbox?limit=20" \
-H "Authorization: Bearer msk_YOUR_API_KEY"Query Parameters
| Param | Type | Default | Notes |
|---|---|---|---|
limit | number | 20 | Results per page (max 100) |
page | number | 1 | Page number |
Response
{
"success": true,
"sends": [
{
"id": "sb_msg_abc123",
"from": "hello@yourdomain.com",
"to": ["test@example.com"],
"subject": "Test Email",
"body_html": "<p>Hello from sandbox!</p>",
"body_text": "Hello from sandbox!",
"headers": {},
"created_at": "2026-04-06T12:00:00Z"
}
],
"total": 3
}DELETE /api/v1/sandbox
Clear all sandbox send history for the account.
curl -X DELETE https://mail.misar.io/api/v1/sandbox \
-H "Authorization: Bearer msk_YOUR_API_KEY"Response
{ "success": true, "deleted": 3 }Sandbox vs. Real Sends
| Behaviour | Sandbox | Production |
|---|---|---|
| Payload validation | ✓ | ✓ |
| Merge tag rendering | ✓ | ✓ |
| Quota deducted | No | Yes |
| Webhook events fired | No | Yes |
| Email delivered | No | Yes |
Stored in /api/v1/sandbox | Yes | No |
message_id prefix | sb_msg_ | msg_ |
Sandbox sends do not consume plan email quota. They are stored for 7 days and automatically purged.
Automation & CI Testing
Set X-MisarMail-Sandbox: true in your test environment's HTTP client configuration to sandbox all API calls without changing application code:
const client = axios.create({
baseURL: 'https://mail.misar.io/api',
headers: {
'Authorization': `Bearer ${process.env.MISARMAIL_API_KEY}`,
...(process.env.NODE_ENV !== 'production'
? { 'X-MisarMail-Sandbox': 'true' }
: {}),
},
});