Error Codes

All MisarMail API errors return a JSON body with success: false and an error string.

{
  "success": false,
  "error":   "Human-readable error message"
}

Validation errors (400) also include a details array:

{
  "success": false,
  "error":   "Validation failed",
  "details": [
    { "field": "to", "message": "Must contain at least one recipient" }
  ]
}

HTTP Status Code Reference

Status	Meaning	Common Causes
`200`	OK	Request succeeded; email delivered
`202`	Queued	Primary SMTP unavailable; email auto-retried
`400`	Bad Request	Invalid request body or failed validation
`401`	Unauthorized	API key missing, invalid, or revoked
`403`	Forbidden	`from.email` not verified, or key lacks scope
`404`	Not Found	Endpoint or resource doesn't exist
`429`	Too Many Requests	Rate limit or plan send limit reached
`500`	Server Error	Unexpected platform error

Error Details

401 — Invalid API Key

{
  "success": false,
  "error":   "Invalid or missing API key. Use: Authorization: Bearer msk_..."
}

Fix: Check that you're sending the correct msk_... key in the Authorization: Bearer header.

403 — Wrong Sender

{
  "success": false,
  "error":   "'from.email' is not a verified account for this API key"
}

Fix: The from.email must match a verified email account in your MisarMail account. Add it in Settings → Email Accounts.

403 — Missing Scope

{
  "success": false,
  "error":   "API key does not have 'send' scope"
}

Fix: Revoke the key and create a new one with the required scope.

400 — Validation Failed

{
  "success": false,
  "error":   "Validation failed",
  "details": [
    { "field": "subject",     "message": "Required" },
    { "field": "to.0.email",  "message": "Invalid email address" }
  ]
}

Fix: Check the details array for per-field error messages.

429 — Plan Limit Reached

{
  "success": false,
  "error":   "Daily send limit reached. Upgrade at mail.misar.io/pricing"
}

Fix: Upgrade your plan or wait for the daily reset at midnight UTC.

202 — Queued (Not an Error)

{
  "success": false,
  "queued":  true,
  "message": "Email queued for retry"
}

Note: Despite success: false, a 202 response is not an error. The email will be delivered automatically when the SMTP provider recovers. Do not retry on 202.

Retry Strategy

Situation	Action
5xx response	Retry with exponential backoff
Network timeout	Retry with exponential backoff
429 Too Many Requests	Wait and retry
4xx response	Fix the request — do not retry
202 Queued	Do nothing — already handled

Use idempotency_key on send requests so retries never cause duplicate emails.