User guide

1. DNS prerequisites

Mail is the hardest sysadmin task because so much of "does it work?" lives in DNS. Get this right before installing missus and the rest is straightforward.

• A hostname for the mail server, e.g. mail.example.com, with an A (and AAAA, if IPv6) record pointing at the box.
• Reverse DNS (PTR) on the public IP pointing back at mail.example.com. Set this at the hosting provider — most receiving MTAs (Gmail, Outlook) reject mail from senders without correct rDNS, and there's nothing missus can do about that.
• For each mail domain you'll host: an MX record example.com → mail.example.com (priority 10 is the default). missus shows you the exact records on the /dns-advice page once you've added the domain.
• Outbound port 25 open. Many providers (DigitalOcean, OVH consumer plans, residential ISPs) block this by default — check before committing to a host.

2. Install missus

curl -fsSL https://apt.netforge.it/free/key.gpg \
    | sudo gpg --dearmor -o /usr/share/keyrings/netforge.gpg
echo "deb [signed-by=/usr/share/keyrings/netforge.gpg] https://apt.netforge.it/free stable main" \
    | sudo tee /etc/apt/sources.list.d/netforge.list
sudo apt update
sudo apt install missus

sudo missus admin create yourname
sudo systemctl start missus

The install pulls in Postfix, Dovecot (with sieve, IMAP, POP, LMTP), Rspamd, certbot, and nftables. The postinst lays out /srv/missus/ (Maildirs, DKIM keys, state.db, backups), generates a 256-bit session secret, and stops there — Postfix and Dovecot are not yet wired to missus's rendered configs. That happens at first Apply.

3. First login

missus binds to 0.0.0.0:8443 by default — the deployment recipe is "missus on a backend host or a private network, panel reachable from your laptop". From your laptop:

ssh -L 8443:127.0.0.1:8443 root@your-mail-server
# then open http://127.0.0.1:8443/ in your browser

Log in, enrol 2FA at /account. Then go to /system/server and set:

• Hostname — exactly what your A/AAAA records point at (e.g. mail.example.com). missus rejects bare names like localhost; an FQDN is required because certbot, DKIM record naming, and SPF mechanism resolution all depend on it.
• Public IPv4, Public IPv6 (if you have one).
• Default DMARC policy: start at quarantine for new domains, escalate to reject once you're confident SPF + DKIM are aligned (see DMARC section below).

4. First mail domain

Go to /domains, click + New domain, enter example.com, set a default mailbox quota (e.g. 1024 MB) and outbound rate limit (e.g. 200/h is sane for personal use; bump to 1000+ for a small team).

On save, missus generates a 2048-bit DKIM keypair under /srv/missus/dkim/example.com.key with selector missus. The public key is what you'll publish to DNS in the next step.

Now click + Generate DKIM if it isn't generated yet, then go to /dns-advice.

5. Publish the DNS records

/dns-advice shows the exact records you need to publish for each domain you've added. There are six per domain:

Paste them at your registrar — or, if you also run nomina, add them as zone records there. Then click Verify on /dns-advice; missus dials the public DNS and reports each row green / yellow / red. Wait until they're all green before issuing TLS or sending real mail.

6. TLS for SMTP/IMAP

Go to /system/certificates, request a Let's Encrypt cert for mail.example.com. missus uses certbot --standalone on port 80 if it's free, or DNS-01 if you've configured a DNS provider plugin (Cloudflare, Route53, …).

On success, missus drops the cert at /etc/letsencrypt/live/mail.example.com/, points Postfix's smtpd_tls_cert_file + Dovecot's ssl_cert at it, and reloads both daemons. The missus-renew systemd timer renews twice a day and runs the same deploy hook.

7. Mailboxes & aliases

Mailboxes are virtual — they don't map to Unix users. Authentication happens against state.db (Argon2id hashes) via Dovecot. The on-disk Maildir lives at /srv/missus/mail/<domain>/<local>/ owned by the system vmail user.

# From the panel: /mailboxes → + New mailbox
#   address: jane@example.com
#   password: (strong password)
#
# From the CLI:
sudo missus mailbox add jane@example.com

Aliases redirect mail without a Maildir. Use them for role addresses, departmental fan-outs, and catch-alls:

# Single redirect
info@example.com  → jane@example.com

# Fan-out (one source, many targets)
sales@example.com  → jane@example.com, mark@example.com

# Catch-all (anything @example.com that isn't a defined mailbox)
@example.com  → jane@example.com

Edit at /aliases, or:

sudo missus alias add info@example.com jane@example.com
sudo missus alias add @example.com jane@example.com

8. DMARC aggregate reports

DMARC report ingest is one of the things you'd otherwise pay $20–200/month for as a SaaS. missus does it inline with the rest of the panel.

On /dmarc/<domain>/enable, missus does three things in one step:

1. Creates a mailbox dmarc@<domain> with a generated password (shown once, then never again — save it).
2. Updates the DMARC TXT record advice to include rua=mailto:dmarc@<domain>. Re-publish the record from /dns-advice.
3. Enables a daily systemd timer (missus-dmarc-poll.timer) that walks the dmarc@ Maildir, ingests attached XML / ZIP / GZ reports, and stores aggregate stats in state.db.

Within 24 h Gmail, Microsoft, Yahoo and dozens of other receivers start mailing reports. The /dmarc/<domain> dashboard shows: total messages observed, alignment percentage, top sources, top failing IPs.

9. Queue & live monitoring

The /queue page reads postqueue -p and lays it out as a sortable table. For each message you can hold, release, requeue, or delete. Filtering by sender or recipient is one click.

The /system/live dashboard auto-refreshes every few seconds and shows: postfix queue depth (active / deferred / hold), dovecot active sessions, Rspamd action breakdown over the last 5 minutes, recent log lines. Useful when you're chasing "did this message land?" in real time.

10. Backups & migration

Everything missus owns lives under /srv/missus/ — Maildirs, state.db, DKIM private keys, certbot live tree. Backup is plain rsync.

sudo rsync -aHAX --delete /srv/missus/ backup-host:/srv/missus-snapshot/

# new box, after `apt install missus`
sudo rsync -aHAX backup-host:/srv/missus-snapshot/ /srv/missus/
sudo missus rehydrate

missus rehydrate re-emits the firewall ruleset, per-mailbox sieve scripts, and the postfix/dovecot/rspamd configs from /srv/missus/ on the new host, then reloads each daemon.

For granular restore (a single mailbox, a whole domain) the /backup page bundles tarballs you can pick apart at restore time.

11. Troubleshooting

First stop:

sudo missus check

Walks filesystem, daemons, listening ports (25/465/587/993/995), postfix wiring (virtual_mailbox_domains, virtual_alias_maps), and reports each step ✓ / ! / ✗.

Daemon logs:

sudo journalctl -u postfix -n 100 --no-pager
sudo journalctl -u dovecot -n 100 --no-pager
sudo journalctl -u rspamd -n 100 --no-pager
sudo journalctl -u missus -n 100 --no-pager

For mail-flow debugging, follow /var/log/mail.log while you send a test message. The Postfix queue ID lets you grep the entire path through smtpd, cleanup, qmgr, smtp.