Automate MailBots with the REST API
The API is read-only and organization-scoped. API keys are shown once and require an active paid subscription.
Authentication
- Open Dashboard → Developer and create a named API key.
- Save the token immediately; only its prefix is displayed later.
- Send the token in the Authorization header. Never place it in a URL, client-side bundle or source repository.
- Base URL
https://api.mailbots.top/v1- Header
Authorization: Bearer mb_live_…- Available scopes
domains:read, messages:read, usage:read
List domains
Requires domains:read. The response includes TXT, MX, probe and provisioning timestamps for each connected domain.
curl -sS https://api.mailbots.top/v1/domains -H 'Authorization: Bearer mb_live_REPLACE_ME'List messages
Requires messages:read. Limit is 1–100. Use the returned next value as the before query parameter to request the next page. Message content expires with the plan retention window.
curl -sS 'https://api.mailbots.top/v1/messages?limit=50' -H 'Authorization: Bearer mb_live_REPLACE_ME'Messages are returned newest first in data. Each one carries these fields:
| Field | Type | Meaning |
|---|---|---|
id | string | Message identifier |
mailbox_id | string | Mailbox that received it |
envelope_to | string | Address it was delivered to, such as build-102@otp.example.com |
from_addr | string or null | Sender address |
subject | string or null | Subject line |
otp | string or null | Verification code detected in the message, or null when none was found |
normalized_payload | string | JSON text holding the body as plain text, as {"text": "…"}. Parse it to read magic links |
raw_size | number | Size of the original message in bytes |
received_at_ms | number | Time received, in Unix milliseconds |
expires_at | number | Time it will be deleted, in Unix seconds |
To wait for one email in a test, poll this endpoint and match on envelope_to. The Playwright and Cypress guides show complete examples.
Read monthly usage
Requires usage:read. Month must use YYYY-MM. The response contains accepted and rejected message counts plus accepted bytes.
curl -sS 'https://api.mailbots.top/v1/usage?month=2026-09' -H 'Authorization: Bearer mb_live_REPLACE_ME'Errors and key hygiene
- 401
Missing, invalid, expired, revoked or insufficiently scoped API key- 422
Invalid query input such as a malformed month- 429
A service quota or rate limit was reached
Revoke a key immediately if it is exposed. Create separate keys for separate systems so each can be revoked independently.