JSON API

Everything the page does is a plain HTTP call. No key needed — the API is bound to the addresses you already know.

Read an inbox

GET/api/inbox/<address>

curl "http://localhost:3000/api/inbox/[email protected]"

{
  "address": "[email protected]",
  "count": 1,
  "messages": [
    {
      "id": "6f1c…",
      "from_name": "GitHub",
      "from_addr": "[email protected]",
      "subject": "Your verification code",
      "intro": "123456 is your code",
      "size": 4210,
      "seen": 0,
      "has_attach": 0,
      "created_at": 1794663637000
    }
  ]
}

Open one message

GET/api/messages/<id>

Returns the full message with html_body, text_body and attachments. Marks it as seen.

Stream new mail (SSE)

GET/api/stream/<address>

Server-Sent Events. Each new message is pushed the moment SMTP has finished receiving it — no polling.

const es = new EventSource("/api/stream/[email protected]");
es.addEventListener("message", (e) => {
  const { type, message } = JSON.parse(e.data);
  if (type === "message") console.log("new mail:", message.subject);
});

Delete a message

DELETE/api/messages/<id>

Attachments

GET/api/attachments/<id>

Returns the raw file with Content-Disposition: attachment.

Connect a domain

POST/api/domains

curl -X POST http://localhost:3000/api/domains \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

Returns the MX record to publish.

POST/api/domains/verify

Resolves the domain's MX records and marks it connected when one points at this server.

Server info

GET/api/config

Mail host, SMTP port, connected domains and counters.

← Back to the inbox