Introduction

How it works

1. Create an inbox. Each inbox has its own SMTP username and password. Make one in the dashboard or with the API.
2. Point your app at it. Change the SMTP host, port, username and password in your staging or test environment. Copy-paste settings for Laravel, Next.js, Rails and Django are on the integrations page.
3. Read what arrived. Open the dashboard, or use the API to list messages, fetch the HTML, check the links, or wait for a specific email in a test.

Quickstart

This takes about five minutes. You need an API key (API_KEY below).

1. Create an inbox

curl -X POST https://app.mailbench.dev/v1/inboxes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging app"}'

{
  "success": true,
  "data": {
    "id": "box_g3bekcev4z7i4psq",
    "name": "Staging app",
    "smtp_username": "…",
    "message_count": 0,
    "created_at": "2026-10-12T10:00:00Z",
    "smtp": {
      "host": "smtp.example.com",
      "ports": [587, 465, 2525],
      "username": "…",
      "password": "shown once"
    }
  }
}

2. Send a test email

Any SMTP client works. With curl:

curl --url 'smtp://smtp.example.com:587' --ssl-reqd \
  --user 'INBOX_USERNAME:INBOX_PASSWORD' \
  --mail-from 'noreply@app.test' \
  --mail-rcpt 'sam@example.org' \
  -T - <<'MAIL'
From: App <noreply@app.test>
To: Sam <sam@example.org>
Subject: Welcome aboard

Click https://app.test/verify/abc123 to confirm your address.
MAIL

3. Wait for it

wait returns the newest matching message in full, immediately if it is already there or as soon as it arrives. It is the call to use in tests.

curl "https://app.mailbench.dev/v1/inboxes/$INBOX_ID/messages/wait?to=sam@example.org&timeout=20" \
  -H "Authorization: Bearer $API_KEY"

const url = new URL("/v1/inboxes/" + process.env.INBOX_ID + "/messages/wait", "https://app.mailbench.dev");
url.searchParams.set("to", "sam@example.org");
url.searchParams.set("timeout", "20");

const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.API_KEY}` } });
const { data } = await res.json();
console.log(data.subject, data.links);

import os, requests

res = requests.get(
    f"https://app.mailbench.dev/v1/inboxes/{os.environ['INBOX_ID']}/messages/wait",
    params={"to": "sam@example.org", "timeout": 20},
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    timeout=25,
)
message = res.json()["data"]
print(message["subject"], message["links"])

Where next

• Test email in CI: assert on the email your app sends, in Jest, PHPUnit, pytest or GitHub Actions.
• Webhooks: get an HTTP call for every new message, and verify it came from us.
• Errors and limits: error codes, rate limits and plan limits.
• API reference: every endpoint, with examples.