Guide
Using a disposable email API for QA and automated testing
End-to-end tests that sign a user up need somewhere for the message to land. A disposable inbox created over the API gives the test an address, a way to wait, and a message it can assert on, without a shared human mailbox.
The flow that matches the API
Create a free key once, with POST /api/v1/keys or the button on the API docs. The JSON field key is the secret. SarabMail stores only a hash, so that response is the only time the full key is shown. Send it as Authorization: Bearer, or as the X-Api-Key header.
In the test, POST /api/v1/inboxes with an empty JSON object. The response inbox has id and address. Give address to your application as the user’s email. Then call GET /api/v1/inboxes/{id}/messages/wait?timeout=8. When the message has arrived, the body is { message: { subject, textBody, ... } }. If the timer ends first, message is null and the HTTP status is still 200.
Why the wait is short
The server clamps timeout to a small maximum so the request fits a serverless limit. In the default configuration that maximum is 8 seconds, and it is never above 60. A test that needs longer should call wait again, poll GET /api/v1/inboxes/{id}/messages, or use the server-sent events stream at GET /api/v1/inboxes/{id}/events.
Pass after as an ISO timestamp when you already have a message and only want a newer one. List results are summaries: id, fromAddress, fromName, subject, preview, receivedAt, and attachmentCount. Reading one message, or the wait response, includes textBody and sanitized htmlBody.
What the free key allows
API Free includes 100 emails a month on public mail domains, with the same short retention as a guest inbox. Creation of keys is limited to five an hour for each network. Higher plans on the pricing page raise the monthly email count. Starter, Team, and Business also include webhooks. The webhook is PUT /api/v1/webhook with an https URL. The signature header is X-SarabMail-Signature, sha256=HMAC of the raw body.
A test should not depend on a permanent address unless the plan allows permanent: true. On the free key, set the test to create a fresh inbox each run. Delete it with DELETE /api/v1/inboxes/{id} when the assertion is done if you do not want to wait for expiry.
Keep production accounts off this path
This is for mail your own system sends into a test inbox. It is a poor database of real customers. The address expires, the domain may be blocked by other providers, and you cannot reply from it.
Do not put a production user’s password reset on a disposable inbox you do not control for the life of the account. Point the test at a staging mailer. Assert on subject or textBody. Avoid asserting on htmlBody markup that your template can change without changing the words.
- One inbox per test run keeps cases from reading each other’s mail.
- Treat message: null as “not yet”, not as a failed HTTP call.
- Remote images in HTML stay blocked unless you pass images=1.
- The API never sends the message. Your application, or your mailer, does.