API reference
The complete, machine-readable description is the OpenAPI 3 document the server publishes at /api/openapi.yaml. Import it into Postman or Insomnia, or feed it to a client generator. This page is the short human version.
Authentication
Everything about a session needs the session secret as a bearer token:
Authorization: Bearer <secret>
The secret is the SMTP password. For a permanent inbox you can also use an API key (ebh_...). Never put the secret in a URL: URLs end up in logs. Creating a session needs no secret, only the bot check described in Limits and plans.
Calls
| Method and path | Purpose |
|---|---|
POST /api/sessions |
Create a session: returns its id, expiry, SMTP settings and public address. Needs a browser's bot-check token, so use the sandbox page. |
GET /api/sessions/{id} |
Describe the session: SMTP host and port, public address, expiry. A cheap liveness check. |
DELETE /api/sessions/{id} |
End the session and delete its mail. |
GET /api/sessions/{id}/messages |
List messages. Filters: after, to, from, subject, source. |
DELETE /api/sessions/{id}/messages |
Delete every message. |
GET /api/sessions/{id}/wait |
Long-poll until matching mail arrives: timeout 1 to 120 s, count 1 to 20, same filters. |
GET /api/sessions/{id}/events |
Live Server-Sent Events stream. Send the bearer header (browsers' EventSource cannot, so use fetch streaming). |
DELETE /api/sessions/{id}/messages/{mid} |
Delete one message. |
GET /api/sessions/{id}/messages/{mid}/raw |
The original message source, as plain text. |
GET /api/sessions/{id}/messages/{mid}/attachments/{n} |
Download an attachment. |
GET /api/sessions/{id}/messages/{mid}/preview-url |
A signed, short-lived link to the sandboxed HTML preview. |
PUT, GET, DELETE /api/sessions/{id}/webhook |
Set, show or remove the webhook (Webhooks). |
GET /api/sessions/{id}/webhook/deliveries |
The last 50 webhook delivery attempts. |
POST /api/sessions/{id}/webhook/test |
Send a signed ping to the webhook. |
GET /api/config |
Public settings of the server (for example whether a bot check is required). |
GET /api/stats |
Public anonymous usage counters. |
Message fields
A message includes, among others: id, seq (a number that only grows within the inbox), receivedAt, source (smtp or inbound), envelopeFrom, envelopeTo, from, to, subject, text, html, headers, attachments, links, codes, size, and for mail from the internet an auth object with the SPF, DKIM and DMARC results. The raw source is only available from the /raw call.
Status codes
| Code | Meaning |
|---|---|
200, 201 |
Success |
204 |
A wait timed out with no matching mail |
400 |
The request is malformed (for example a bad filter or webhook address) |
401 |
Missing or wrong secret |
404 |
The session or message does not exist (it may have expired) |
429 |
Too many requests or simultaneous waits |
503 |
The server is restarting or busy: retry after the Retry-After header |
Errors are JSON: {"error": "..."}.