Maddy Mail Server

Last reviewed Sep 13, 2026 · 822 words

A traditional mail server is Postfix, Dovecot, OpenDKIM, an auth backend and a TLS shim, five processes with five config syntaxes that all have to agree. Maddy is one process, one config file and one binary, and it replaces every one of them on 256 MB of RAM. It is the mail server I would hand to someone who understands DNS and wants to own their inbox without learning Postfix's 800 parameters. What it cannot do is make email deliverability easy, because that problem lives outside the server, and the honest guide to self-hosted email should be read before this one.

Everything in one config file, and it reads top to bottom

Maddy's config is a Caddyfile-style block format. The default maddy.conf shipped in the image is about 150 lines and already describes a complete server: an inbound SMTP endpoint on 25 that checks SPF, DKIM and DMARC and delivers to local mailboxes; a submission endpoint on 465 and 587 that authenticates users and signs outgoing mail with DKIM; an IMAP endpoint on 993; and the storage backend, which is SQLite by default with the message bodies on disk. You change the hostname and the primary domain, and it runs.

services:
  maddy:
    image: foxcpp/maddy:latest
    environment:
      - MADDY_HOSTNAME=mx1.example.org
      - MADDY_DOMAIN=example.org
    ports:
      - "25:25"
      - "143:143"
      - "465:465"
      - "587:587"
      - "993:993"
    volumes:
      - ./data:/data
      - ./certs:/data/certs:ro
    restart: unless-stopped

Users are two commands, because Maddy separates credentials from mailboxes:

docker exec -it maddy maddy creds create [email protected]
docker exec -it maddy maddy imap-acct create [email protected]

Forget the second one and login succeeds while IMAP reports no mailbox, which is the most common first-day support question in the project's tracker.

DKIM is generated for you; the DNS is still yours

On first start Maddy creates a DKIM key pair per domain under /data/dkim_keys/ and writes a .dns file next to it containing the exact TXT record to publish. That is more than Postfix will ever do. It does not, and cannot, publish that record, set up the SPF and DMARC records, configure reverse DNS on your IP, or persuade your ISP to unblock outbound port 25. Those four items decide whether Gmail accepts your mail, and they are all in the DNS guide for self-hosters. Budget an hour for them and a week of sending test messages to yourself before trusting the setup with anything important.

TLS is the one place to make a decision. The default expects certificate files you supply, which pairs well with a Caddy or Traefik instance already renewing certificates for the host; mount the same files read-only and reload. Maddy also has a built-in ACME loader if this box has no other certificate machinery, and either path is a 3-line config change.

What is missing, plainly

No webmail; pair it with a client such as Roundcube or SnappyMail if you want a browser interface. No Sieve or server-side filtering rules at last check, so sorting into folders happens in your mail client. Spam filtering is a hook into an external rspamd rather than a bundled filter, and running without rspamd on a public MX means the built-in SPF and DMARC checks are your only defence, which is thin. No admin UI of any kind: it is the CLI and the config file. And the community is small, so a problem outside the documented paths means reading Go source or waiting on GitHub rather than finding a decade of forum threads.

The bigger sibling to consider first

Stalwart is the other single-binary mail server, written in Rust, and it bundles what Maddy leaves out: JMAP alongside IMAP, a web admin panel, Sieve, a built-in spam filter, and a larger contributor base. It costs more memory and more configuration surface. Maddy wins on minimalism and on the reading time of its config; Stalwart wins on features and on the odds that the thing you need next is already there. For the batteries-included Postfix-based alternative, docker-mailserver wraps the traditional stack in one container and inherits its enormous body of documentation. All three sit in the email category.

What I'd do

For a single domain and a handful of mailboxes on a VPS with a clean IP and port 25 open, run Maddy with rspamd next to it, mount certificates from the reverse proxy you already run, and spend the saved complexity budget on getting DNS and reverse DNS exactly right. Keep the /data directory in nightly backups, because the SQLite database, the mailboxes and the DKIM keys all live there. If you expect to want webmail, filtering rules and an admin UI within the year, start on Stalwart instead and skip the migration.