API documentation

Authentication

Send the key as Authorization: Bearer sm_live_… or in the X-Api-Key header. SarabMail stores only a SHA-256 hash of the secret.

A free key can be minted on this page. Creation is limited to five keys an hour for each network.

curl https://sarabmail.com/api/v1/usage \
  -H "Authorization: Bearer sm_live_…"

Tiers

API Free includes 100 emails a month on public mail domains. Starter is $12/mo or $9/mo yearly for 5,000 emails. Team is $39/mo or $29/mo yearly for 50,000 emails and one private subdomain. Business is $99/mo or $79/mo yearly for 300,000 emails and 3 private domains. Enterprise starts at $299.

Plus is $3.99/mo or $29/yr: no ads, 10 inboxes, 30-day storage, and the reserved domain pool. Pro is $7.99/mo or $59/yr: permanent inboxes, a custom domain, a forwarding hook, and a light API. Paddle checkout is the billing hook. Nothing is charged until the Paddle keys are set.

Inboxes

POST /inboxes creates an address on a mail-pool domain, never on sarabmail.com. An empty body mints a random name. Pass localPart and domain to choose one. ttlMinutes is clamped to the plan maximum. permanent: true is for Pro, Business, and Enterprise.

curl -X POST https://sarabmail.com/api/v1/inboxes \
  -H "Authorization: Bearer sm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"inbox.example"}'

Messages

GET /inboxes/{id}/messages returns summaries. Reading one message returns text and sanitized HTML. Remote images stay blocked unless you pass ?images=1.

DELETE the message, or DELETE the inbox, to remove it and its files.

Long-poll

GET /inboxes/{id}/events holds a short server-sent stream and wakes from a Postgres notification when mail arrives. GET /inboxes/{id}/messages/wait?timeout=8 holds until a message arrives or the timer ends. The cap stays short so it fits a serverless limit. Pass after as an ISO timestamp to skip mail you already have.

curl "https://sarabmail.com/api/v1/inboxes/INBOX_ID/messages/wait?timeout=8" \
  -H "Authorization: Bearer sm_live_…"

Webhooks

Plans that include webhooks can PUT /webhook with an https URL. SarabMail posts JSON with event message.received. X-SarabMail-Signature is sha256=HMAC(secret, raw body). The signing secret is returned when you set the URL.

Domains

GET /domains lists the domains your plan can use. Pro and Business add a domain with POST /domains, publish a TXT record sarabmail-verify=…, then call POST /domains/verify. Team and Business request a private subdomain with POST /domains/subdomain and { "label": "acme" }. Mail does not flow until Cloudflare Email Routing or an MX record is in place.

Errors

Errors use { "error": { "code", "message" } }. 401 means the key is missing or revoked, 403 means the plan does not allow it, 409 means the address is taken, and 429 includes Retry-After. Authenticated responses also send X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.