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
- Generate a unique address for the run, such as
signup-1731916800@otp.example.com. No setup is needed per address. - Submit it to the signup, login or password-reset form of the app you are testing.
- Poll
GET /v1/messageswithto=set to that address until the message is there. - Read
otpfrom 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:readandusage: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
| Plan | Messages a month | Kept for | Domains |
|---|---|---|---|
| Trial, 14 days | 500 | 24 hours | Ready hostname under trial.mailbots.top |
| Starter, $10 a month | 5,000 | 72 hours | 1 of your own |
| Pro, $15 a month | 25,000 | 72 hours | 5 of your own |
| Status | Body | Meaning |
|---|---|---|
| 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.