DOCSEARCHbyAlgolia
Submit Docs

Bulwark Webmail Documentation

repository·main·Indexed 21 days ago

https://github.com/bulwarkmail/webmail

A modern, self-hosted webmail client built with Next.js and the JMAP protocol, specifically designed for Stalwart Mail Server. It provides a full suite of applications for Mail, Calendar, Contacts, and File management. Features include a web-based setup wizard, Unified Mailbox support, and comprehensive keyboard shortcuts for email navigation.

Tokens
20.2K
Snippets
76
Records
98
Agent score
73%

What's inside Bulwark Webmail

  1. Understand the Bulwark Webmail tech stack

    main

    Bulwark Webmail is built using a modern web stack optimized for performance and JMAP protocol support:

    • Framework: Next.js 16 (App Router) and React 19
    • Language: TypeScript
    • Styling: Tailwind CSS v4
    • State Management: Zustand
    • Protocol: Custom JMAP client (RFC 8620)
    • Rich Text Editor: Tiptap
    • Internationalization: next-intl
    • Icons: Lucide React
    • Testing: Vitest and Playwright

  2. Configure Mailbox and Account Boundaries

    main

    Bulwark Webmail uses a Unified Mailbox that combines Inbox, Sent, Drafts, Junk, Archive, and Trash.

    By default, the Unified Mailbox is scoped to the active account and its shared/group folders. However, an administrator can enable a cross-account mode that spans every connected account.

    Key mailbox behaviors:

    • All mail, Unread, and Starred views obey the current account boundary (either single-account or cross-account if enabled by an admin).
    • Users can narrow these views to specific per-account folder selections.
    • Every message row explicitly names the folder the message originated from.

  3. Configure Bulwark Webmail via environment variables

    main
    While most settings are managed via the setup wizard or admin dashboard, you can use environment variables to override these values. Environment variables always take precedence over admin-managed values. Note that NEXT_PUBLIC_* variables are baked in at build time and cannot be changed via environment variables in a pre-built Docker image without rebuilding.

  4. Manage Multi-account Identities

    main

    Users can run several accounts simultaneously, each maintaining its own session.

    Key Features:

    • Account Switcher: Shows connection status and allows setting a default account.
    • Sender Identities: Multiple identities per account, each with its own signature, synced automatically.
    • Sub-addressing: Supports user+tag@domain.com with configurable delimiters.
    • Delegated Accounts: Shared and group accounts appear alongside personal folders. If "Include group inboxes" is enabled, they are merged into the Unified Mailbox.
    • Custom Endpoints: If ALLOW_CUSTOM_JMAP_ENDPOINT is enabled, users can enter custom JMAP endpoints on the login form.

  5. Manage Mail Attachments and Files

    main

    The mail composer and viewer support advanced attachment handling:

    • Upload/Download: Supports drag-and-drop embedding and downloading to the local file system.
    • Previews: Images and PDFs render inline on both desktop and mobile. .eml (message/rfc822) parts are displayed as nested emails.
    • TNEF Support: Automatically extracts winmail.dat files and unwraps message/rfc822 parts.
    • Safety: The composer provides a warning if you mention an attachment in the text but forget to include it.

  6. Admin Setup and Configuration

    main

    The first launch triggers a Setup Wizard that configures JMAP servers, OAuth/OIDC, session secrets, logging, branding, and the admin password. The wizard writes to the admin config directory to keep .env.local clean.

    Directory Management:

    • ADMIN_CONFIG_DIR: Contains operator-authored configuration. Can be mounted read-only after setup.
    • ADMIN_STATE_DIR: Holds runtime audit logs and login timestamps.

    Secret Management: JSON configuration can read secrets from files for Docker/Kubernetes secret mounts using keys like:

    • passwordHashFile
    • sessionSecretFile
    • oauthClientSecretFile

  7. Manage Files via JMAP FileNode

    main

    Bulwark allows browsing Stalwart's native JMAP FileNode storage as a standard folder tree.

    Key Operations:

    • Upload: Supports streamed WebDAV PUT uploads, including entire folders with progress tracking.
    • File Management: Supports cut, copy, paste, duplicate, and favorites.
    • Sharing (RFC 9670): Files and folders can be shared with users or groups using a principal picker. Permissions include read, read/write, or manager.
    • Organization: View files in Grid or List modes, sorted by name, size, or date.

  8. Use the web-based setup wizard

    main

    Since version 1.6.4, Bulwark includes a web-based setup wizard that runs on first launch. This eliminates the need to manually edit .env.local or shell into a container. The wizard guides you through:

    • Server: Probing JMAP endpoints and toggling Stalwart features.
    • Auth: Configuring OAuth2/OIDC discovery or basic-auth fallback.
    • Security: Generating a SESSION_SECRET and opting into settings sync.
    • Logging: Selecting log format (text/JSON) and level.
    • Branding: Uploading favicons, logos, and legal URLs.
    • Admin: Setting the initial admin password and optionally enabling read-only mode via a .config-locked marker.

    The wizard writes configuration to ADMIN_CONFIG_DIR (defaults to ./data/admin).

  9. Configure Build-Time Variables (Subpaths and Locales)

    main

    Certain variables are baked into the application at build time via Next.js and cannot be changed via environment variables in a pre-built Docker image. To use these, you must build your own image using --build-arg.

    Default Locale

    Use NEXT_PUBLIC_DEFAULT_LOCALE to set the fallback language. Supported locales include ar, ca, cs, da, de, en, es, fa, fr, he, hu, it, ja, ko, lv, nl, pl, pt, ro, ru, sk, tr, uk, zh.

    Subpath / Reverse Proxy

    To serve the webmail at a subpath (e.g., https://example.com/webmail), set NEXT_PUBLIC_BASE_PATH. You must also set NEXT_PUBLIC_LOCALE_PREFIX=always to avoid rewrite loops. Your reverse proxy should point to the container without stripping the prefix.

    Example Build Command:

    docker build --build-arg NEXT_PUBLIC_BASE_PATH=/webmail -t bulwark-webmail .
    docker build --build-arg NEXT_PUBLIC_DEFAULT_LOCALE=de -t bulwark-webmail .

# For subpaths:
docker build --build-arg NEXT_PUBLIC_BASE_PATH=/webmail -t bulwark-webmail .

  10. Quick start with Bulwark Webmail

    main

    You can deploy Bulwark Webmail using Docker or by building from source. On first launch, a web-based setup wizard will guide you through configuring the server, authentication, security, branding, and admin settings. If you provide JMAP_SERVER_URL via environment variables, the wizard will be skipped in favor of an environment-managed configuration flow.

    ### Docker

```bash
docker run -d -p 3000:3000 ghcr.io/bulwarkmail/webmail:latest

    Or with Docker Compose:

    docker compose up -d

    From source

    git clone https://github.com/bulwarkmail/webmail.git
cd webmail
npm install
npm run build && npm start
# Then open http://localhost:3000 to run the setup wizard

  11. Configure Security and Authentication

    main

    Bulwark Webmail includes several enterprise-grade security features:

    • Authentication: Supports OAuth2 / OIDC with PKCE (compatible with Keycloak, Authentik, or the built-in provider), OAuth-only mode, and TOTP two-factor authentication.
    • S/MIME: Manage certificates to sign, encrypt, decrypt, and verify messages. Keys are isolated per account.
    • Email Integrity: Surfaces SPF, DKIM, and DMARC indicators. It automatically drops the "via" badge on spoofed mail.
    • Content Security: Uses DOMPurify for HTML sanitization, enforces CSP with per-request nonces, and includes SSRF redirect validation and sandboxed PDF iframes.

  12. Configure Calendar and Tasks

    main

    Bulwark provides a full calendar suite with the following capabilities:

    • Views: Month, week, day, and agenda views, plus a sidebar mini-calendar and task list.
    • Event Management: Drag-to-reschedule, click-drag to create, and edge-pull to resize (snaps to 15-minute increments). Supports recurring events with scope selection (this occurrence, following, or all).
    • Invitations: Supports iMIP (RFC 5545 / 6047) with organizer/attendee panels and RSVP trust assessment.
    • Import/Subscription: Supports .ics detection in emails, iCalendar import (with UID deduplication), and editable webcal subscriptions.
    • Tasks: Includes due dates, priority levels, and completion status.
    • Sync: Uses JMAP push for real-time synchronization.