API reference

Base URL

Every endpoint lives under /v1 on the same origin as the dashboard. Use HTTPS.

https://app.mailbench.dev/v1

Authentication

Send an API key as a bearer token. Create keys in the dashboard; each belongs to one workspace and is either read or read_write. See Authentication.

curl https://app.mailbench.dev/v1/inboxes \
  -H "Authorization: Bearer $API_KEY"

Responses

Every response is a JSON envelope with a success flag. On success, the result is in data:

{
  "success": true,
  "data": { }
}

On failure there is an error with a stable code to switch on and a message for people:

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Inbox not found"
  }
}

See Errors and limits for every code, rate limits and plan limits.

Pagination

List endpoints return up to limit items (1 to 200, default 50), newest first. When there are more, the response has a top-level next_cursor. Pass it back as cursor to get the next page. Stop when it is absent.

curl "https://app.mailbench.dev/v1/inboxes/$INBOX_ID/messages?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $API_KEY"

Changes over time

New fields and endpoints can appear in /v1 at any time. Write clients that ignore fields they do not know.

OpenAPI description

The whole API is described in an OpenAPI 3 document (version 1.0.0). Download it to generate a client, or import it into Postman, Insomnia or Bruno.

Download openapi.yaml

Resources

• Inboxes: An inbox has its own SMTP username and password.
• Messages: Captured emails.
• Waiting: Block until an email arrives. Built for CI.
• Tags: Label messages by hand or with rules.
• Webhooks: Signed HTTP callbacks for new messages.
• Checks: HTML, link and spam analysis of a message.
• Sending: Put a message into an inbox over HTTP, without SMTP.
• Testing: Rendered views and failure simulation.
• Workspace: The workspace your key belongs to.