You are currently browsing documentation for the 1.7 branch. Documentation for the stable 1.8 branch can be found here.

Frequently asked questions


Where to ask questions?

First, please read this FAQ to check if your question is listed here. Simple questions best fit in our Matrix room. For more complex questions, you can always open a new issue on GitHub. We actively monitor the issues list.

My installation is broken!

We’re sorry to hear that. Please check for common mistakes and troubleshooting advice in the Technical issues section of this page.

I think I found a bug!

If you did not manage to solve the issue using this FAQ and there is not any open issues describing the same problem, you can continue to open a new issue on GitHub.

I want a new feature or enhancement!

Great! We are always open for suggestions. We currently maintain two tags:

Please check if your idea (or something similar) is already mentioned there. If there is one open, you can choose to vote with a thumbs up, so we can estimate the popular demand. Please refrain from writing comments like “me too” as it clobbers the actual discussion.

If you can’t find anything similar, you can open a new issue. Please also share (where applicable):

  • Use case: how does this improve the project?

  • Any research done on the subject. Perhaps some links to upstream website, reference implementations etc.

Why does my feature/bug take so long to solve?

You should be aware that creating, maintaining and expanding a mail server distribution requires a lot of effort. Mail servers are highly exposed to hacking attempts, open relay scanners, spam and malware distributors etc. We need to work in a safe way and have to prevent pushing out something quickly.

TODO: Move the next section into the contributors part of docs We currently maintain a strict work flow:

  1. Someone writes a solution and sends a pull request;

  2. We use Travis-CI for some very basic building and testing;

  3. The pull request needs to be code-reviewed and tested by at least two members from the contributors team.

Please consider that this project is mostly developed in people their free time. We thank you for your understanding and patience.

I would like to donate (for a feature)

Donations are welcome to the authors of the project directly, we do not manage any central donation pot. Also, check the file for Patreon link or equivalent. If you wish to contact a contributor specifically, please do so on Matrix

Technical issues

In this section we are trying to cover the most common problems our users are having. If your issue is not listed here, please consult issues with the troubleshooting tag.

Changes in .env don’t propagate

Variables are sent to the containers at creation time. This means you need to take the project down and up again. A container restart is not sufficient.

docker-compose down && \
docker-compose up -d

Issue reference: 615.

403 - Access Denied Errors

While this may be due to several issues, check to make sure your DOMAIN= entry is the first entry in your HOSTNAMES=.

TLS certificate issues

When there are issues with the TLS/SSL certificates, Mailu denies service on secure ports. This is a security precaution. Symptoms are:

  • 403 browser errors;

These issues are typically caused by four scenarios:

  1. TLS_FLAVOR=notls in .env;

  2. Certificates expired;

  3. When TLS_FLAVOR=letsencrypt, it might be that the certbot script is not capable of obtaining the certificates for your domain. See letsencrypt issues

  4. When TLS_FLAVOR=certs, certificates are supposed to be copied to /mailu/certs. Using an external letsencrypt program, it tends to happen people copy the whole letsencrypt/live directory containing symlinks. Symlinks do not resolve inside the container and therefore it breaks the TLS implementation.

letsencrypt issues

In order to determine the exact problem on TLS / Let’s encrypt issues, it might be helpful to check the logs.

docker-compose logs front | less -R
docker-compose exec front less /var/log/letsencrypt/letsencrypt.log

Common problems:

  • Port 80 not reachable from outside.

  • Faulty DNS records: make sure that all HOSTNAMES have A (IPv4) and AAAA (IPv6) records, pointing the the BIND_ADDRESS4 and BIND_ADDRESS6.

  • DNS cache not yet expired. It might be that old / faulty DNS records are stuck in a cache en-route to letsencrypt’s server. The time this takes is set by the TTL field in the records. You’ll have to wait at least this time after changing the DNS entries. Don’t keep trying, as you might hit rate-limits.

Copying certificates

As mentioned above, care must be taken not to copy symlinks to the /mailu/certs location.

The wrong way!:

cp -r /etc/letsencrypt/live/ /mailu/certs

The right way!:

mkdir -p /mailu/certs
cp /etc/letsencrypt/live/ /mailu/certs/key.pem
cp /etc/letsencrypt/live/ /mailu/certs/cert.pem

See also Managing of external Let’s encrypt certificates.

Issue reference: 426, 615.

How do I activate DKIM and DMARC?

Go into the Domain Panel and choose the Domain you want to enable DKIM for. Click the first icon on the left side (domain details). Now click on the top right on the “Regenerate Keys” Button. This will generate the DKIM and DMARC entries for you.

Issue reference: 102.

Do you support Fail2Ban?

Fail2Ban is not included in Mailu. Fail2Ban needs to modify the host’s IP tables in order to ban the addresses. We consider such a program should be run on the host system and not inside a container. The front container does use authentication rate limiting to slow down brute force attacks.

We do provide a possibility to export the logs from the front service to the host. For this you need to set LOG_DRIVER=journald or syslog, depending on the log manager of the host. You will need to setup the proper Regex in the Fail2Ban configuration. Be aware that webmail authentication appears to come from the Docker network, so don’t ban those addresses!

Issue reference: 85, 116, 171, 584, 592.

Users can’t change their password from webmail

All users have the abilty to login to the admin interface. Non-admin users have only restricted funtionality such as changing their password and the spam filter weight settings.

Issue reference: 503.

rspamd: DNS query blocked on

This usually relates to the DNS server you are using. Most of the public servers block this query or there is a rate limit. In order to solve this, you most probably are better off using a root DNS resolver, such as unbound. This can be done in multiple ways:

  • Use the Mailu/unbound container. This is an optional include when generating the docker-compose.yml file with the setup utility.

  • Setup unbound on the host and make sure the host’s /etc/resolve.conf points to local host. Docker will then forward all external DNS requests to the local server.

  • Set up an external DNS server with root resolving capabilities.

In any case, using a dedicated DNS server will improve the performance of your mail server.

Issue reference: 206, 554, 681.

Is there a way to support more (older) ciphers?

See How can I override settings? . You will need to add the protocols you wish to support in an override for the front container (Nginx).

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers <list of ciphers>;

We strongly advice against downgrading the TLS version and ciphers!

Issue reference: 363, 698.

A user gets Sender address rejected: Access denied. Please check the message recipient […] and try again even though the sender is legitimate?

First, check if you are really sure the user is a legitimate sender, i.e. the registered user is authenticated successfully and own either the account or alias he/she is trying to send from. If you are really sure this is correct, then the user might try to errornously send via port 25 insteadof the designated SMTP client-ports. Port 25 is meant for server-to-server delivery, while users should use port 587 or 465.