Email testing API

An email testing API for signup and OTP tests

MailBots gives your tests a real inbox on a subdomain you own, such as otp.example.com. Every address there is accepted, so each test run can sign up with a fresh one. Your test then calls the REST API with that exact address and gets the message back with the one-time code already extracted, or receives it as a signed webhook. Plans start at $10 a month, with a 14-day trial.

No card, no DNS.Or start free with thebrowser extension

How a test uses the API

  1. Generate a unique address for the run, such as signup-1731916800@otp.example.com. No setup is needed per address.
  2. Submit it to the signup, login or password-reset form of the app you are testing.
  3. Poll GET /v1/messages with to= set to that address until the message is there.
  4. Read otp from the response, type it into the form and finish the flow.
ADDR="signup-$(date +%s)@otp.example.com"
submit_signup_form "$ADDR"   # your app's step
for attempt in $(seq 1 20); do
  OTP=$(curl -sS "https://api.mailbots.top/v1/messages?to=$ADDR&limit=1" \
    -H "Authorization: Bearer $MAILBOTS_API_KEY" | jq -r '.data[0].otp // empty')
  [ -n "$OTP" ] && break
  sleep 3
done
echo "OTP: $OTP"

The Playwright and Cypress guides show the same loop inside a real test, with timeouts.

What the response contains

Each message comes back newest first in data, with next as the cursor for the following page.

{
  "data": [
    {
      "id": "msg_…",
      "envelope_to": "signup-1731916800@otp.example.com",
      "from_addr": "noreply@example.dev",
      "subject": "Your verification code",
      "otp": "847291",
      "normalized_payload": "{\"text\":\"Your code is 847291…\"}",
      "received_at_ms": 1731916803512,
      "expires_at": 1732176003
    }
  ],
  "next": "1731916803512:msg_…"
}

otp is null when no code was found, as in a magic-link email. Parse normalized_payload to read the text and pull the link out yourself. The API reference lists every field.

Keys and scopes

  • Create a key under Dashboard → Developer. It is shown once; only its prefix stays visible.
  • Pick only the scopes a system needs: messages:read, domains:read and usage:read.
  • Send it as Authorization: Bearer mb_live_…. Keep it in your CI secret store, never in a URL or a client bundle.
  • Use one key per system, so each can be revoked on its own.

The API only reads. It cannot send email, delete messages or change your account.

Webhooks instead of polling

Register an HTTPS endpoint and MailBots posts each new message to it as a message.received event, with the detected otp. Every request is signed with HMAC-SHA256 over the timestamp and raw body, and failed deliveries are retried for about 12 hours. The webhook guide shows the payload and how to verify the signature.

Polling is simpler for a test that waits on one address. Webhooks suit a service that reacts to every message.

Agents and the command line

The same key works with the MCP server, so coding agents such as Claude Code or Cursor can read the code during a signup test, and with the CLI for shell scripts.

Limits and errors

PlanMessages a monthKept forDomains
Trial, 14 days50024 hoursReady hostname under trial.mailbots.top
Starter, $10 a month5,00072 hours1 of your own
Pro, $15 a month25,00072 hours5 of your own
StatusBodyMeaning
401{"error":"invalid_api_key"}Missing, wrong, revoked or expired key, a missing scope, or no active plan
422{"error":"invalid_recipient"}to is not a single email address
422{"error":"invalid_month"}month is not in YYYY-MM form

Questions

Do I need my own domain?

Not for the trial, which comes with a ready hostname under trial.mailbots.top. Paid plans use a subdomain of your own, connected with one TXT and one MX record, as the DNS guide explains. Mail for your main domain is not touched.

Is there a free API?

No. The free extension and Telegram bot are for manual testing. The API needs the trial or a paid plan.

Can tests run in parallel?

Yes. Give each run its own address and filter with to=, so parallel jobs never read each other's mail.