mailbox-search

Read-only HTTP search API over a Mail-in-a-Box Maildir tree.

What it does

Serves message metadata, bodies, and attachments out of /home/user-data/mail/mailboxes without writing to the mail data. Per-token scoping (single domain or all mailboxes), per-token IP pinning, rate limiting, and an audit log of every request.

Endpoints

• GET/health — liveness probe (no auth).
• GET/mailboxes — list mailboxes the token can see.
• POST/search — query (q, from, to, subject, since/until, domain, user, limit, offset, deep).
• GET/message/:id — parsed message (headers, body, attachment metadata).
• GET/message/:id/raw — raw RFC 822.
• GET/message/:id/attachment/:index — single attachment by index.

Auth

Every endpoint except /health requires Authorization: Bearer <token>. Tokens are issued and revoked from the admin console below.

The admin console is restricted to loopback and any IPs configured via ADMIN_ALLOW at install time. From elsewhere it returns 404.

Full reference: API docs and operator README are linked from the admin console once you log in.