Installation & initial configuration

This is the practical guide on how to set up a mail server using maddy for personal use. It omits most of the technical details for brevity and just gives you the minimal list of things you need to be aware of and what to do to make stuff work.

For purposes of clarity, these values are used in this tutorial as examples, wherever you see them, you need to replace them with your actual values:

Getting a server

Where to get a server to run maddy on is out of the scope of this article. Any VPS (virtual private server) will work fine for small configurations. However, there are a few things to keep in mind:

Installing maddy

Your options are:

Host name + domain

Open /etc/maddy/maddy.conf with vim^W your favorite editor and change the following lines to match your server name and domain you want to handle mail for. If you setup a very small mail server you can use in both fields. However, to easier a future migration of service, it's recommended to use a separate DNS entry for that purpose. It's usually, mx2, etc. You can of course use another subdomain, for instance: An email failover server will become possible if you forward to another server (as long as you configure it to handle your domain).

$(hostname) =
$(primary_domain) =

If you want to handle multiple domains, you still need to designate one as "primary". Add all other domains to the local_domains line:

$(local_domains) = $(primary_domain)

TLS certificates

One thing that can't be automagically configured is TLS certs. If you already have them somewhere - use them, open /etc/maddy/maddy.conf and put the right paths in. You need to make sure maddy can read them while running as unprivileged user (maddy never runs as root, even during start-up), one way to do so is to use ACLs (replace with your actual paths):

$ sudo setfacl -R -m u:maddy:rX /etc/ssl/ /etc/ssl/

maddy reloads TLS certificates from disk once in a minute so it will notice renewal. It is possible to force reload via systemctl reload maddy (or just killall -USR2 maddy).

Let's Encrypt and certbot

If you use certbot to manage your certificates, you can simply symlink /etc/maddy/certs into /etc/letsencrypt/live. maddy will pick the right certificate depending on the domain you specified during installation.

You still need to make keys readable for maddy, though:

$ sudo setfacl -R -m u:maddy:rX /etc/letsencrypt/{live,archive}

If you use to manage your certificates, you could simply run:

mkdir -p /etc/maddy/certs/ --force --install-cert -d \
  --key-file       /etc/maddy/certs/  \
  --fullchain-file /etc/maddy/certs/

First run

systemctl daemon-reload
systemctl start maddy

Well, it should be running now, except that it is useless because we haven't configured DNS records.

DNS records

How it is configured depends on your DNS provider (or server, if you run your own). Here is how your DNS zone should look like:

; Basic domain->IP records, you probably already have them.   A   AAAA  2001:beef::1

; It says that "server is handling messages for".   MX    10
; Of course, mx1 should have an entry as well:   A

; Use SPF to say that the servers in "MX" above are allowed to send email
; for this domain, and nobody else.   TXT   "v=spf1 mx -all"

; Opt-in into DMARC with permissive policy and request reports about broken
; messages.   TXT    "v=DMARC1; p=none;"

And the last one, DKIM key, is a bit tricky. maddy generated a key for you on the first start-up. You can find it in /var/lib/maddy/dkim_keys/example.org_default.dns. You need to put it in a TXT record for domain, like that:    TXT   "v=DKIM1; k=ed25519; p=nAcUUozPlhc4VPhp7hZl+owES7j7OlEv0laaDEDBAqg="


By default SMTP is not protected against active attacks. MTA-STS policy tells compatible senders to always use properly authenticated TLS when talking to your server, offering a simple-to-deploy way to protect your server against MitM attacks on port 25.

Basically, you to create a file with following contents and make it available at

mode: enforce
max_age: 604800

Note: in the file is your MX hostname, In a simple configuration, it will be the same as your hostname In a more complex setups, you would have multiple MX servers - add them all once per line, like that:


User accounts and maddyctl

A mail server is useless without mailboxes, right? Unlike software like postfix and dovecot, maddy uses "virtual users" by default, meaning it does not care or know about system users.

IMAP mailboxes ("accounts") and authentication credentials are kept separate.

To register user credentials, use maddyctl creds create command. Like that:

$ maddyctl creds create

Note the username is a e-mail address. This is required as username is used to authorize IMAP and SMTP access (unless you configure custom mappings, not described here).

After registering the user credentials, you also need to create a local storage account:

$ maddyctl imap-acct create

That is it. Now you have your first e-mail address. when authenticating using your e-mail client, do not forget the username is "", not just "postmaster".

You may find running maddyctl creds --help and maddyctl imap-acct --help useful to learn about other commands. Note that IMAP accounts and credentials are managed separately yet usernames should match by default for things to work.