bongo/docs/web.md

Webmail and user administration

The Python 3 bongo-web service supplies the classic Bongo Webmail layout, user settings, tasks, contacts, calendars, and the restricted administrator view. It talks to the same Store used by IMAP and the delivery agents; it is not a second mailbox database.

Deployment

The suffixless web configuration document is the only Web listener configuration. A normal deployment listens on loopback port 8080 behind Apache, nginx, nginx-proxy-manager, or HAProxy. Set public_base_url, external_https, trusted_proxies, and client_ip_header to describe the real external path. Forwarded client addresses are trusted only from the configured proxies.

Bongo can instead serve HTTPS directly. It loads the configured certificate and private key, binds the privileged HTTPS and redirect ports, then permanently changes to the bongo UID/GID before accepting requests. The HTTP listener redirects to the configured HTTPS base URL except for the narrowly scoped ACME HTTP-01 challenge path. Reverse-proxy examples are installed below /usr/share/bongo/examples/reverse-proxy.

Sessions and security

Login creates a server-side session with an HttpOnly cookie. State-changing API requests require the session's CSRF token. Login attempt windows, session lifetime, second-factor lifetime, and second-factor attempt limits are configurable. TOTP fields are shown only when the account has enabled that optional feature; recovery codes and app passwords are handled by the shared authentication subsystem.

HTML mail is sanitized before display. Safe inline or explicitly permitted images can remain useful for signatures and normal content, while active markup and unwanted remote tracking are blocked. Administrator actions are both role-checked and limited to a fixed command set; selecting the administration view does not create a second login session.

User functions

The current API and interface cover mailbox folders and conversations, reading and sending mail, contacts, calendar events, filters, actionable tasks, external account collection, sending identities, preferences, and signatures. A task is a workflow item: it can be opened for its details and then dismissed, retried, ignored, or completed where the task type permits. English, German, and every installed gettext catalogue use the same API instead of hard-coded interface text.

The administrator view exposes health and a restricted set of validated actions. Full server configuration remains the responsibility of bongo-admin and the configuration TUI; Webmail must not become an arbitrary root command interface.

The current classic interface is the 0.7 baseline. The responsive PWA redesign is scheduled for 0.8 and documented separately in web-pwa.md. JMAP and background Web Push belong to 0.9.