Abulu Mail API

A JSON REST API for the self-hosted Abulu Mail server. Base URL is your deployment origin — for the hosted instance, https://abulu.net. All responses are JSON.

Overview

Abulu Mail is a receive-only mail server. The API has two access tiers:

Public — no auth. List active domains and mint disposable addresses.

User — Authorization: Bearer <token>. Read your own mailbox (token from /api/login or /api/temp).

Authentication

User endpoints authenticate with a bearer token scoped to a single mailbox:

Token	Header	Obtained via	Scope
User token	`Authorization: Bearer …`	`POST /api/login` or `POST /api/temp`	Single mailbox

Errors & limits

401 — missing / invalid / expired token.
404 — mailbox or message not found.
429 — rate limit exceeded (per client IP).
403 — action disabled (e.g. sending on a receive-only server).
List endpoints paginate via ?limit=&offset= (limit clamped to 1–200).
User tokens expire after 7 days.

Public

GET/api/domainsPublic

List active (MX-verified) domains available for creating temporary addresses.

Response

{ "domains": ["bolobeo.com", "kansavic.com"] }

POST/api/tempPublic

Create a disposable mailbox. Returns the address, a plaintext password, and a user token scoped to that inbox.

domain (optional) — domain to use; defaults to first active. local (optional) — local part before @; random if omitted.

Request

curl -X POST https://abulu.net/api/temp \
  -H "Content-Type: application/json" \
  -d '{"domain":"bolobeo.com"}'

Response

{
  "email": "happypanda4283f4k2x@bolobeo.com",
  "password": "Ab12Cd…",
  "domain": "bolobeo.com",
  "expiresAt": null,
  "token": "eyJ…",
  "login": { "imap": {...}, "pop3": {...}, "webmail": "/mail.html" }
}

User

POST/api/loginPublic

Request

curl -X POST https://abulu.net/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@bolobeo.com","password":"s3cret"}'

Response

{ "token": "eyJ…", "email": "alice@bolobeo.com" }

GET/api/mailboxesBearer

List the authenticated user's mailboxes with message counts.

Response

{ "mailboxes": [ { "name": "INBOX", "total": 3, "unseen": 1 } ] }

GET/api/mailboxes/:name/messagesBearer

List messages in a mailbox, newest first. Paginate with ?limit=&offset=.

Request

curl "https://abulu.net/api/mailboxes/INBOX/messages?limit=50" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "messages": [ { "uid": 1, "from": "…", "subject": "…", "date": 1750…, "seen": false, "size": 108 } ],
  "total": 1, "limit": 50, "offset": 0
}

GET/api/mailboxes/:name/messages/:uidBearer

Read a single message (parsed text, HTML and attachment metadata). Marks it seen.

Response

{ "uid": 1, "subject": "…", "from": "…", "to": "…", "date": "…",
  "text": "…", "html": "…", "attachments": [], "spam": 0 }

POST/api/mailboxes/:name/messages/:uid/seenBearer

Mark a message read/unread. Body { "seen": true | false }.

Response

{ "ok": true }

POST/api/sendBearer

Always returns 403 — Abulu Mail is receive-only and does not send or relay outbound mail.

{ "error": "This server is receive-only; sending is disabled." }