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://api.misar.io/mail/v1/send \
  -H "Authorization: Bearer msk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-MisarMail-Sandbox: true" \
  -d '{
    "from":    { "email": "[email protected]" },
    "to":      [{ "email": "[email protected]" }],
    "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://api.misar.io/mail/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":       "[email protected]",
      "to":         ["[email protected]"],
      "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://api.misar.io/mail/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_ |

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://api.misar.io/mail',
  headers: {
    'Authorization': `Bearer ${process.env.MISARMAIL_API_KEY}`,
    ...(process.env.NODE_ENV !== 'production'
      ? { 'X-MisarMail-Sandbox': 'true' }
      : {}),
  },
});