How to Administer and Maintain a Mailu Server

Mailu is administered through three complementary interfaces: the web administration interface for day-to-day domain, user, and alias management; the mailu command-line tool for host-level operations; and a RESTful API for automation. Spam filtering runs as a separate service with its own auto-learning and greylisting behavior. This guide covers what each interface does, how to reach it, and what to check when something stops working.

The web administration interface

The admin interface is the primary place for routine changes. According to the project documentation, it covers:

• Global admins — accounts that can manage every domain on the server.
• Per-domain delegation — you can hand a domain to a manager who only sees that domain, without granting global rights.
• Announcements — messages shown to users in the webmail.
• Quotas — per-user storage limits.

Typical tasks and where they live:

The same interface also exposes user-facing features — aliases, auto-reply, auto-forward, fetched accounts, and ManageSieve — so most requests from end users can be resolved without touching the server shell.

The Mailu command line

The mailu CLI is the tool for operations that sit outside the web UI: inspecting container state, running maintenance commands, and performing upgrades. Because Mailu ships as a set of Docker images, most command-line work happens in the context of your Docker Compose (or Kubernetes) deployment rather than inside a single long-running process.

Practical pattern:

1. Input — you run a mailu subcommand from the directory holding your docker-compose.yml (or against the Kubernetes deployment).
2. Action — the command acts on the running stack, for example to check status or apply a configuration change.
3. Expected result — the stack reflects the change, and docker compose ps (or the equivalent) shows the affected containers healthy again.

If a command appears to do nothing, confirm you are in the deployment directory and that your environment variables (domain, hostnames, secrets) are the ones the running stack was started with — a mismatch between the shell environment and the deployed configuration is the most common cause of confusing CLI behavior.

The RESTful API

For anything you would otherwise repeat by hand — bulk user creation, syncing accounts from an external directory, wiring Mailu into a provisioning pipeline — use the RESTful API instead of scripting the web UI. The API is documented alongside the rest of the project documentation, and it exposes the same administrative objects the web interface manages.

Two maintenance notes that matter here:

• Version your documentation. The docs are written inside the repository and evolve with it. Always read the documentation matching the Mailu version you actually run — a 2024.06 server should be read against the 2024.06 docs, not the latest.
• Pin your image tags. Because the project ships versioned releases (2024.06, 2.0, 1.9, and earlier), an unpinned latest tag turns a routine restart into an unplanned upgrade.

Spam filtering and security maintenance

Antispam is a first-class part of Mailu rather than an add-on. The documented capabilities include:

• Auto-learn — the filter adjusts from mail it has classified.
• Greylisting — temporary deferral of unknown senders.
• DMARC and SPF — policy checks against your published DNS records.
• Anti-spoofing — rejection of forged sender identities.

On the security side, Mailu enforces TLS and supports DANE, MTA-STS, Let's Encrypt certificate issuance, outgoing DKIM signing, an anti-virus scanner, Snuffleupagus hardening, and blocking of malicious attachments.

Maintenance implications:

• DNS is part of the server. SPF, DKIM, DMARC, MTA-STS, and DANE all depend on records you publish. If mail is being rejected or marked as spam by recipients, check DNS before touching the Mailu configuration.
• Certificates renew on their own when Let's Encrypt is configured, but renewal fails silently if DNS or the reverse proxy is misconfigured. Verify after any DNS or proxy change.
• Auto-learn means behavior drifts. A filter that has learned from a mislabeled message will keep applying that lesson; correct misclassifications rather than ignoring them.

Routine maintenance checklist

• Before upgrading: read the release notes for the target version and the matching documentation version. The project publishes notes per release (2024.06, 2.0, 1.9, 1.8, and back to Freeposte.io 1.2), and breaking changes are listed there.
• Back up the database. Mailu supports more than one database back-end, and the documentation includes a section on changing it — which means the database is a component you can and should treat as movable and backed up.
• Review delegation and global admins periodically. Per-domain delegation is a convenience that is easy to forget after staff changes.
• Watch quotas. Quota exhaustion is a common, easily-missed cause of "mail stopped arriving."
• Keep the reverse proxy in mind. Mailu documents using an external reverse proxy; if TLS or webmail breaks after a proxy change, that is the first place to look.

Common sticking points

• Reading the wrong docs version. The documentation is versioned with the code. Mismatched docs produce instructions that do not match your menus.
• Treating the web UI as the only interface. Bulk or repeatable work belongs in the API; host-level work belongs in the CLI.
• Assuming spam settings are static. Auto-learn and greylisting change over time; review rather than set-and-forget.
• Forgetting that DNS is configuration. DKIM, SPF, DMARC, MTA-STS, and DANE are all DNS-side, and all can break mail delivery without any change on the server itself.

Where to start

If you are new to the server, work through the setup documentation for your version first, then use the demonstration server to see the admin interface and webmail before configuring your own. Once running, treat the web admin interface as your daily tool, the CLI as your maintenance tool, and the API as your automation tool — and keep the documentation version aligned with the Mailu version you deployed.