Community fork of stalwartlabs/webui with UI improvements and fixes.
This is a community fork of stalwartlabs/webui maintained by LinkPhoenix, focused on UI/UX improvements: mobile-friendly layouts, dark mode polish, additional color themes, a command palette, a calendar date/time picker, and several list/form refinements. Several of these have already been contributed back and shipped in official Stalwart WebUI releases.
Stalwart WebUI is a schema-driven single-page application for administering Stalwart. After authentication the panel fetches a JSON schema from the server and dynamically generates all forms, lists, navigation, and layouts from that schema — the schema is the single source of truth, not the UI code.
This fork tries to stay aligned with that philosophy: any AI agent or contributor working on it follows the rules in AGENTS.md, and the small number of deliberate exceptions where the UI does something the official schema doesn't (yet) support are tracked, with the ideal server-side fix for each, in SCHEMA_DEVIATIONS.md.
See CHANGELOG.md for the full list of changes in this fork.
Official Stalwart repositories:
- stalwartlabs/stalwart — the mail server itself.
- stalwartlabs/webui — the official admin WebUI this project forks.
- stalwartlabs/cli —
stalwart-cli, used below to point a server at a WebUI build.
Key features (shared with upstream):
- Schema-driven UI: All forms, lists, and navigation are generated from a JSON schema fetched from
/api/schemaafter login. No object types, field names, or layouts are hardcoded. - JMAP protocol: All data operations (queries, creates, updates, deletes, blob uploads) use JMAP (RFC 8620) with method chaining and result references.
- Permission-aware: Every button, link, field, and section respects the user's permissions. Elements the user cannot access are hidden.
Additions in this fork:
- Community Overview: inventory cards (directory, mail readiness, access & apps, reports) with attention badges for queue backlog, certificate expiry, and report problems — separate from the Enterprise live-metrics Dashboard.
- Getting Started checklist: first-run checklist (domain, DKIM, TLS cert, admin account; optional DMARC) with deep links and docs — shown in the sidebar only while required steps remain (no flash on completed installs).
- Usable on mobile: admin lists, forms, and the sidebar work on narrow viewports instead of assuming desktop.
- Selectable color themes (Stalwart, Ocean, Forest, Violet, Rose, Amber, Teal) with light/dark, square/rounded corners, and list density (comfortable / compact).
Ctrl+K/Cmd+Kcommand palette to search pages, form sections, and fields — including Overview / Appearance keywords (queue,theme, …).- In-app Changelog in the header menu (published versions only; no
[Unreleased]). - Calendar date/time picker replacing native date inputs, themed for dark mode.
- Accounts list: Role and Usage/Quota columns with coloured progress bars, plus a highlight and recalculate hint for stale negative disk-usage values.
- CSV export and bulk Change quota… on admin lists (Accounts/Groups for quota).
- Sieve: Active column on System/User script lists; syntax-highlighted foldable script editor; expand-to-fit on long textareas.
- Aliases counts: Accounts, Groups, Domains, and Mailing Lists lists all show an Aliases column.
- Sortable list columns: the most relevant column on every list (Accounts, Groups, Domains, Mailing Lists, Roles) can be sorted client-side.
- Roles list: Enabled/Disabled Permissions count columns, so you can see a role's scope without opening it.
- User menu: current account name/email and an account switcher in the header dropdown, alongside Appearance settings.
- Mailboxes list: shown as an indented hierarchy instead of a flat list.
- Queued messages: empty/backlog guidance with links to Delivery Trace and Log Entries; Size shown as human units (B / KB / MB / GB / TB), including when the schema still marks the field as a plain integer.
- Byte sizes everywhere: list, detail, and form fields for byte quantities (
size, quotas, …) use the same dynamic unit ladder — no unitless1,254-style counts. - Store / DNS type icons: brand assets for known backends (S3→AWS, PostgreSQL, Redis, Cloudflare, …) plus Lucide stand-ins for FileSystem, Default, Sharded, ElasticSearch, LDAP, and DNS providers without a local logo — paths respect Stalwart’s
/admin(or/account) mount so icons work in production, not only in local Vite. - Log Entries: client-side Level/Event filters (“Exact match only”), named presets, optional auto-refresh, and a rate-limited Refresh button.
- Report lists: Pass/Quarantine/Reject (DMARC), Successful/Failed Sessions (TLS), Incidents + Feedback Type (ARF); coloured badges when non-zero; Problems only toggle.
- Open in new tab: sidebar, header menu, list Create/rows, command palette, and Back/Cancel use real links so middle-click and the browser context menu work.
| Capability | Community / OSS | Enterprise |
|---|---|---|
| Overview inventory + attention badges | Yes | Yes |
| Getting Started checklist | Yes | Yes |
| Directory / reports / queue / logs (schema + JMAP) | Yes (per permissions) | Yes |
| Live-metrics Dashboard, Live Tracing | Locked / hidden | Yes (with permissions) |
| Appearance, Changelog, command palette | Yes | Yes |
Deliberate client workarounds where the official schema cannot express a feature yet are listed in SCHEMA_DEVIATIONS.md. Merging upstream WebUI: docs/UPSTREAM_SYNC.md.
Captured against a local dev server seeded with sample data (see DEVELOPMENT.md) — all addresses below are examples (@example.org), not real accounts.
| Overview — inventory + attention badges | Getting Started checklist |
 |
 |
| Accounts — Usage/Quota + Aliases columns | Roles — permission counts |
 |
 |
| Groups — Usage/Quota + Aliases columns | Domains — Aliases column |
 |
 |
| Mailing Lists — Aliases column | User menu (header) |
 |
 |
| Appearance — light mode + list density | Appearance — dark mode, Stalwart theme |
 |
 |
| Queued messages — backlog + ops links | Log Entries — exact-match filters, presets, auto-refresh |
 |
 |
| DMARC inbox — summary columns | TLS inbox — Problems only + failed sessions |
 |
 |
| ARF inbox — Incidents + Feedback Type | Command palette (theme → Appearance) |
 |
 |
| Changelog (in-app) | Accounts — Export CSV + quota bars |
 |
 |
| Bulk Change quota… | List empty — no filter matches |
 |
 |
| System Sieve scripts — Active column | Sieve script editor (syntax highlight) |
 |
 |
| Expand to fit content (long textareas) | |
 |
Stalwart WebUI ships as part of Stalwart Mail Server. To install Stalwart Mail Server on your server, follow the instructions for your platform:
All documentation is available at stalw.art/docs/get-started. Note that a standard Stalwart install ships the official WebUI; see Switching your server to this fork's UI below to point your server at this fork instead.
Stalwart serves its admin UI as a managed WEBAPP application, downloaded from a URL you control — switching to this fork (or back to upstream) is a server-side config change, no rebuild or redeploy of Stalwart itself required. This is done with stalwart-cli.
On your server:
export STALWART_URL=https://subdomain.domain.com
export STALWART_USER='user@domain.com'
export STALWART_PASSWORD='Password'
Find the id of your WEBAPP application:
stalwart-cli query Application
Point it at this fork's latest release instead of upstream's:
stalwart-cli update Application ID WEBAPP \
--field https://github.com/LinkPhoenix/stalwart-webui-fork/releases/latest/download/webui.zip
Then trigger the update:
stalwart-cli create Action/UpdateApps
Every tagged release of this fork publishes a webui.zip build via CI (see .github/workflows/build.yml), so pointing at releases/latest/download/webui.zip always fetches the newest tested build. To go back to the official UI, repeat the update step with https://github.com/stalwartlabs/webui/releases/latest/download/webui.zip.
Prerequisites:
- Node.js 18 or later
- A running Stalwart instance (for JMAP API calls) — see DEVELOPMENT.md for how to spin up a disposable local test server with Docker, no manual Stalwart setup required.
Install dependencies:
npm install
Configuration is done through Vite environment variables. Copy or edit .env.development in the project root:
VITE_API_BASE_URL=http://localhost:443
VITE_OAUTH_CLIENT_ID=stalwart-webui
VITE_ACCESS_TOKEN=
VITE_OAUTH_SCOPES=
| Variable | Description |
|---|---|
VITE_API_BASE_URL |
URL of the Stalwart server. Used for all API requests during development. In production builds (when empty or unset) requests are relative to the current origin. |
VITE_OAUTH_CLIENT_ID |
OAuth 2.0 client ID. Defaults to stalwart-webui. |
VITE_ACCESS_TOKEN |
When set, skips the OAuth flow entirely and uses this token for all requests. Useful for local development and testing. |
VITE_OAUTH_SCOPES |
Optional OAuth scopes. Omitted from the authorization request when empty. |
Set VITE_ACCESS_TOKEN to a valid bearer token to skip the login page and go straight to the admin panel:
VITE_ACCESS_TOKEN=your-bearer-token-here
Against the local test server from DEVELOPMENT.md, scripts/dev-token.ps1 / scripts/dev-token.sh fetch one for you automatically.
npm run dev
This starts Vite's development server with hot module replacement, typically at http://localhost:5173.
Run the unit tests (Vitest):
npm test
Run tests in watch mode:
npm run test:watch
npm run build
This runs the TypeScript compiler followed by Vite's production build. Output
goes to the dist/ directory.
To preview the production build locally:
npm run preview
For bugs or questions about this fork's UI changes, please open an issue on this repository.
For anything related to Stalwart Mail Server itself, do not hesitate to reach the upstream team on Github Discussions, Reddit, Discord or Matrix. Additionally you may purchase a subscription to obtain priority support from Stalwart Labs LLC.
This project is dual-licensed under the GNU Affero General Public License v3.0 (AGPL-3.0; as published by the Free Software Foundation) and the Stalwart Enterprise License v1 (SELv1):
- The GNU Affero General Public License v3.0 is a free software license that ensures your freedom to use, modify, and distribute the software, with the condition that any modified versions of the software must also be distributed under the same license.
- The Stalwart Enterprise License v1 (SELv1) is a proprietary license designed for commercial use. It offers additional features and greater flexibility for businesses that do not wish to comply with the AGPL-3.0 license requirements.
Each file in this project contains a license notice at the top, indicating the applicable license(s). The license notice follows the REUSE guidelines to ensure clarity and consistency. The full text of each license is available in the LICENSES directory.
As a fork, all changes made here — including new files added by this fork — remain under the same dual license as the upstream project; this is reflected in the SPDX license notice at the top of every source file.
Copyright (C) 2024, Stalwart Labs LLC