Skip to content

Admin panel

Administrators get an in-app settings panel at /admin for the instance-wide configuration that used to require editing environment variables and restarting the container. It's linked from the mail shell for any user whose account has admin access (see Auth and user model for how that's granted).

Every value shown here is DB-first with an environment-variable fallback: if a setting has never been saved from this panel, Mailclient falls back to the matching env var from .env, then to a built-in default. Saving a value here overrides the env var for this instance immediately, without a restart. Leaving .env in place is still fine — it just becomes the pre-first-save default.

The panel has five tabs, listed down the left side: Branding, Security Mail, Limits & Timeouts, DAV, and Admins & Users.

Branding

Controls the logo, favicon, fonts, app title, and footer text shown throughout the mail UI. Each asset (logo, favicon, fonts CSS) can be set two ways:

  • Paste a URL to an externally hosted asset, or
  • Upload a file directly. Uploaded files are stored locally under assets/uploads/branding/ and preview immediately next to the field.

Leaving both the URL and file fields blank for a given asset keeps whatever is currently configured — you don't need to re-enter values you're not changing. Uploading a fonts.css file only hosts that stylesheet; if it references font files via @font-face src: url(...), those still need to resolve from wherever the CSS points them.

Security Mail

The SMTP sender used for account-security email: 2FA emailed bypass codes, new sign-in alerts, and password-reset-request notices to admins. This is separate from the per-instance SMTP_HOST/SMTP_PORT mail transport used to send users' own mail — use a dedicated low-privilege mailbox or service account here rather than reusing anyone's personal mailbox password.

Leave the password field blank when saving to keep the current password unchanged; entering a new value replaces the stored (encrypted) password.

Limits & Timeouts

Session lifetimes, in minutes, and size caps, in megabytes:

  • Session idle timeout — how long a signed-in session can sit unused before re-authentication is required.
  • Session absolute timeout — the maximum total lifetime of a session regardless of activity.
  • "Remember me" session timeout — the maximum session and cookie lifetime when a user checks Remember me at login.
  • Max message size to open — messages larger than this are refused before Mailclient parses them into memory.
  • Max remote image size — the cap enforced by the signed remote-image proxy when a user opts in to loading remote images in a message.
  • Default timezone — only used to localize an example placeholder in the UI (the contact-form phone-number field); it does not change the container's clock or any user's own timezone preference.

Each timeout field shows a caption underneath with the equivalent in hours or days once it crosses that threshold, so a value like 43200 minutes reads as "≈ 30 days" at a glance.

DAV

Tuning for the shared CalDAV/CardDAV HTTP client used by Nextcloud sync. Individual CalDAV/CardDAV accounts are still configured per-user under Settings > Calendar & Contacts — these settings only affect the underlying HTTP client every account's sync goes through:

  • Request timeout (seconds) — how long a single DAV HTTP request is allowed to take.
  • Max response size (MB) — the largest DAV response accepted during discovery and sync.
  • Allow connecting to plain http:// DAV servers — off by default; only enable this for a trusted LAN/dev Nextcloud instance that has no TLS. HTTPS targets are always allowed regardless of this setting.

Admins & Users

Lists every local user account. Accounts aren't created here — anyone with valid mailbox credentials can sign in, and Mailclient auto-creates the local account record on first successful login. This tab only manages accounts that already exist:

  • Role — a toggle per row. Switching it on makes that user an admin; switching it off returns them to a regular user. It saves immediately (no separate Save button), and reverts on-screen if the change is rejected — Mailclient always refuses to demote the last remaining admin, to avoid locking everyone out of this panel.
  • Disabled — a toggle that blocks sign-in for that account without deleting anything. Use Save on that row to apply it. Mailclient always refuses to disable the last remaining admin, for the same reason it refuses to demote one. Toggling this (in either direction) invalidates that account's existing sessions, so a session opened before a disable can't silently regain access just because the account is re-enabled later.
  • 2FA — shows whether authenticator 2FA is currently enabled for the account. Check reset and Save to clear a user's TOTP secret (for example, after a lost device), which lets them set it up again from scratch.
  • Reset user data, at the bottom, clears a named user's saved preferences and 2FA state entirely. They can still sign back in with their mailbox credentials and are re-provisioned as a fresh account. This is meant for a full local-state reset, not routine account management — it asks for confirmation before submitting. Refused for the last remaining admin, since it would delete their account row (and admin role) along with everything else.

Promoting or demoting a user's admin role takes effect on their next request: an already-open session picks up the change immediately rather than waiting for that session to expire.