Siomail API

A JSON REST API. Default base URL: http://localhost:8080. Authenticated endpoints require the header Authorization: Bearer <token>.

Temp-mail flow

1. GET /api/domains → fetch the list of domains to choose from.
2. POST /api/temp → create a random address, receive a token + password.
3. GET /api/mailboxes/INBOX/messages → poll the inbox.
4. GET /api/mailboxes/INBOX/messages/:uid → read a single email.

List domains

GET/api/domains

Returns the active domains (used for the dropdown).

curl http://localhost:8080/api/domains

{ "domains": ["siomail.local", "example.com"] }

Create random mail

POST/api/temp

curl -X POST http://localhost:8080/api/temp \
  -H "Content-Type: application/json" -d '{"domain":"siomail.local"}'

{
  "email": "swiftfox1234@siomail.local",
  "password": "Ab12Cd...",
  "domain": "siomail.local",
  "expiresAt": 1750000000000,
  "token": "eyJ...",            // use as Authorization: Bearer
  "login": { "imap": {...}, "pop3": {...}, "smtp": {...}, "webmail": "/mail.html" }
}

Read email

GET/api/mailboxes — list mailboxes (INBOX, Sent, Junk...).

GET/api/mailboxes/:name/messages — list emails in a mailbox.

GET/api/mailboxes/:name/messages/:uid — a single email (text + html + attachments).

curl http://localhost:8080/api/mailboxes/INBOX/messages \
  -H "Authorization: Bearer $TOKEN"

{ "messages": [ { "uid": 1, "from": "...", "subject": "...", "date": 1750..., "seen": false } ] }

Other actions:

• POST/api/mailboxes/:name/messages/:uid/seen — mark as read.

Login (token)

POST/api/login — sign in to a regular account and receive a token.

curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@siomail.local","password":"s3cret"}'

{ "token": "eyJ...", "email": "alice@siomail.local" }

Login via IMAP / POP3

Every account (including temporary mailboxes) can be read with standard clients:

The username is the full email address; the password comes from POST /api/temp or is set by the admin.