Sandbox mode intercepts outbound emails and stores them instead of delivering them via SMTP. Use it during development and integration testing to verify payloads without sending real messages.

Enabling Sandbox Mode

A send is sandboxed when either of these is true:

The request includes the header X-MisarMail-Sandbox: true, or
The API key carries the sandbox scope.

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": "hello@yourdomain.com" },
    "to":      [{ "email": "test@example.com" }],
    "subject": "Test Email",
    "html":    "<p>Hello from sandbox!</p>"
  }'

The payload is parsed and stored, but the send short-circuits before SMTP delivery — no real email is sent and no send quota is deducted.

Response (the stored send's message_id is prefixed sandbox_):

{
  "success":    true,
  "message_id": "sandbox_1a2b3c4d5e6f7890",
  "provider":   "sandbox",
  "timestamp":  "2026-04-06T12:00:00Z"
}

Endpoints

Method	Path	Description
`GET`	`/api/v1/sandbox`	List recent sandbox sends
`DELETE`	`/api/v1/sandbox`	Clear sandbox send history

Both endpoints authenticate with an msk_ API key of any scope — sandbox sends are scoped per user.

GET /api/v1/sandbox

Returns up to the 50 most recent sandbox sends for the account, newest first. This endpoint takes no query parameters.

curl "https://api.misar.io/mail/v1/sandbox" \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{
  "success": true,
  "sends": [
    {
      "id":           "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "from_address": "hello@yourdomain.com",
      "to_addresses": ["test@example.com"],
      "subject":      "Test Email",
      "html":         "<p>Hello from sandbox!</p>",
      "message_id":   "sandbox_1a2b3c4d5e6f7890",
      "metadata":     { "tags": [], "source": "v1/send" },
      "created_at":   "2026-04-06T12:00:00Z"
    }
  ],
  "total": 1
}

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 }

Sandbox vs. Real Sends

Behaviour	Sandbox	Production
Payload parsed and stored	Yes	—
Quota deducted	No	Yes
Email delivered via SMTP	No	Yes
Retrievable via `GET /api/v1/sandbox`	Yes	No
`message_id` prefix	`sandbox_`	provider-assigned

Sandbox sends do not consume send quota. They persist until you clear them with DELETE /api/v1/sandbox.

Automation & CI Testing

Set X-MisarMail-Sandbox: true in your test environment's HTTP client so all API calls are sandboxed 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' }
      : {}),
  },
});

Sandbox Mode