For developers
A temporary email API that receives the message your test sends
The SarabMail API creates an address on a mail domain and returns the message that arrives for it. The same product is what people mean by a temp mail API, a disposable email API, or a receive email API: a key, an inbox, and a wait.
Authentication
The base URL on this deployment is https://sarabmail.com/api/v1. Send the key as Authorization: Bearer sm_live_… or in the X-Api-Key header. SarabMail stores only a hash of the secret.
Create a free key with the button on the docs page, or with POST /api/v1/keys. The key field in that JSON is the secret, and it is shown only then. Key creation is limited to five an hour for each network. API Free includes 100 emails a month on public mail domains.
Create an inbox, then read the mail
POST /api/v1/inboxes with an empty JSON object {} mints a random address on a domain your plan allows. That domain is never sarabmail.com. The response includes inbox.id and inbox.address. Pass localPart and domain when you want a specific name.
GET /api/v1/inboxes/{id}/messages/wait?timeout=8 stays open until a message arrives or the timer ends. The server clamps timeout to a short maximum, 8 seconds in the default configuration, and never above 60. If nothing arrived, the body is { "message": null } and the status is 200. When mail has arrived, message includes subject, textBody, and sanitized htmlBody. GET /api/v1/inboxes/{id}/messages lists summaries: id, fromAddress, fromName, subject, preview, receivedAt, and attachmentCount.
What the API will not do
It does not send email. Your app, or your mailer, sends to inbox.address. SarabMail hands back what was delivered.
Remote images stay blocked unless you pass images=1. Plans that include webhooks set one with PUT /api/v1/webhook and an https URL. X-SarabMail-Signature is sha256=HMAC(secret, raw body). The docs page covers errors, domains, and the event stream.
Quick start
curl
curl -sS -X POST https://sarabmail.com/api/v1/inboxes \
-H "Authorization: Bearer $SARABMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# Response: { "inbox": { "id": "...", "address": "...", ... } }
# Then wait. timeout is clamped by the server (8 seconds by default).
INBOX_ID="inbox id from the response"
curl -sS "https://sarabmail.com/api/v1/inboxes/$INBOX_ID/messages/wait?timeout=8" \
-H "Authorization: Bearer $SARABMAIL_API_KEY"
# { "message": null } means nothing arrived yet.
# Otherwise message.subject and message.textBody are the mail.Python
import os
import requests
base = "https://sarabmail.com/api/v1"
headers = {
"Authorization": f"Bearer {os.environ['SARABMAIL_API_KEY']}",
"Content-Type": "application/json",
}
created = requests.post(f"{base}/inboxes", headers=headers, json={})
created.raise_for_status()
inbox = created.json()["inbox"]
print(inbox["address"])
waited = requests.get(
f"{base}/inboxes/{inbox['id']}/messages/wait",
headers=headers,
params={"timeout": 8},
)
waited.raise_for_status()
message = waited.json()["message"]
if message is None:
print("No message yet. Call wait again.")
else:
print(message["subject"])
print(message["textBody"])Node.js
const base = "https://sarabmail.com/api/v1";
const headers = {
Authorization: `Bearer ${process.env.SARABMAIL_API_KEY}`,
"Content-Type": "application/json",
};
const created = await fetch(`${base}/inboxes`, {
method: "POST",
headers,
body: "{}",
});
if (!created.ok) throw new Error(`create inbox failed: ${created.status}`);
const { inbox } = await created.json();
console.log(inbox.address);
const waited = await fetch(`${base}/inboxes/${inbox.id}/messages/wait?timeout=8`, { headers });
if (!waited.ok) throw new Error(`wait failed: ${waited.status}`);
const { message } = await waited.json();
console.log(message?.subject ?? "No message yet. Call wait again.");curl · free key
curl -sS -X POST https://sarabmail.com/api/v1/keys \
-H "Content-Type: application/json" \
-d '{"name":"qa"}'
# The secret is the "key" field. It is shown only in this response.Questions about the email API
Does the API send email?
No. It receives mail that your system sends to the address you created.
How do I authenticate?
Send Authorization: Bearer and the key, or send the X-Api-Key header. Create a free key on the docs page or with POST /api/v1/keys.
Is there a free trial?
Yes. API Free includes 100 emails a month on public mail domains, with no card, until you start a paid plan. Paid API limits and prices are on the pricing page.
Why does wait return so quickly?
timeout is clamped to a short maximum so the request fits a serverless limit. The default cap is 8 seconds. Call it again, list messages, or use the events stream if the mail is slow.