Errors

Every error carries a machine code, a human message and a fix: the exact command or change that resolves it.

Error shape

Errors use standard HTTP status codes and always have the same body. Match on code, show message to people, and act on fix.

{
  "error": {
    "code": "inbox_limit_reached",
    "message": "the free plan allows 3 inboxes",
    "fix": "Delete an inbox with `mailbay inbox delete <id>` or upgrade your plan"
  }
}

Error codes

invalid_api_key

401

The API key is missing or invalid.

FixCreate a key in the dashboard under Keys and send it as Authorization: Bearer <key>

insufficient_scope

403

This API key is limited to one inbox.

FixUse an org scoped API key

not_found

404

The inbox, message or thread does not exist, or belongs to another organization.

FixCheck the id. List what you can see with mailbay inbox list

route_not_found

404

No such endpoint.

FixSee the API reference for the list of /v1 endpoints

invalid_body

400

The request body is not valid JSON for this endpoint.

FixSend JSON like {"local_part":"support","display_name":"Support"}; both fields are optional

invalid_query

400

A query parameter is not valid.

FixUse ?limit=1..100 and the next_cursor from the previous page

invalid_local_part

400

The inbox name is not valid.

FixUse 1 to 64 letters, digits, dots, hyphens or underscores

inbox_exists

409

An inbox with that address already exists.

FixPick another inbox name

inbox_limit_reached

402

Your plan's inbox limit is reached.

FixDelete an inbox with mailbay inbox delete <id> or upgrade your plan

sandbox_recipient_not_allowed

403

Without a verified domain, mailbay.email addresses can only email members of the workspace.

FixVerify your own domain to email anyone: mailbay domain add <domain>

catch_all_cannot_send

403

The Catch-all inbox only receives.

FixCreate an inbox with the address you want to send from

internal

500

Something went wrong on our side. The details are in our logs, not in the response.

FixRetry with the same Idempotency-Key. If it keeps happening, contact us with the time of the request