matrix-docker-ansible-deploy/docs/configuring-playbook-email.md

Adjusting email-sending settings (optional)

By default, this playbook sets up an Exim relay SMTP mailer service (powered by exim-relay and the ansible-role-exim-relay Ansible role), through which all Matrix services send emails.

With the default setting, exim-relay attempts to deliver emails directly with the address matrix@matrix.example.com, as specified by the exim_relay_sender_address playbook variable. See below if you want to configure the playbook to relay email through another SMTP server.

The Ansible role for exim-relay is developed and maintained by the MASH (mother-of-all-self-hosting) project. For details about configuring exim-relay, you can check them via:

• 🌐 the role's documentation at the MASH project online
• 📁 roles/galaxy/exim_relay/docs/configuring-exim-relay.md locally, if you have fetched the Ansible roles

Why use exim-relay?

You might wonder whether you need exim-relay or whether you can configure SMTP directly in each service (like Synapse, Matrix Authentication Service, etc.).

Here are the benefits of using exim-relay:

1. Final delivery capability: If you don't have an SMTP server, exim-relay can deliver emails directly. This makes it a complete solution for sending email from your Matrix services.

2. Centralized configuration: Even if you have an existing SMTP server, configuring it separately in each Matrix component (Synapse, Matrix Authentication Service, bridges, bots, etc.) creates additional work and maintenance burden. With exim-relay, you configure your upstream SMTP server once in the exim-relay settings, and then simply point all other services to exim-relay. They automatically start using your upstream SMTP server without needing individual SMTP configuration.

3. Local spooling and reliability: If your upstream SMTP server becomes temporarily unavailable (but exim-relay itself is still running), exim-relay will store messages locally and automatically retry delivery later. This prevents email loss during temporary outages and improves the overall reliability of your email delivery.

In summary, exim-relay provides significant benefits with minimal overhead, serving as a reliable intermediary that simplifies configuration and improves resilience.

Firewall settings

No matter whether you send email directly (the default) or you relay email through another host, you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).

Docker automatically opens these ports in the server's firewall, so you likely don't need to do anything. If you use another firewall in front of the server, you may need to adjust it.

Adjusting the playbook configuration

Enable DKIM authentication to improve deliverability (optional)

By default, exim-relay attempts to deliver emails directly. This may or may not work, depending on your domain configuration.

To improve email deliverability, you can configure authentication methods such as DKIM (DomainKeys Identified Mail), SPF, and DMARC for your domain. Without setting any of these authentication methods, your outgoing email is most likely to be quarantined as spam at recipient's mail servers.

For details about configuring DKIM, refer this section on the role's documentation.

💡 If you cannot enable DKIM, SPF, or DMARC on your domain for some reason, we recommend relaying email through another SMTP server.

Relaying email through another SMTP server (optional)

On some cloud providers such as Google Cloud, port 25 is always blocked, so sending email directly from your server is not possible. In this case, you will need to relay email through another SMTP server.

For details about configuration, refer this section on the role's document.

Disable mail service (optional)

For a low-power server you might probably want to disable exim-relay. To do so, add the following configuration to your inventory/host_vars/matrix.example.com/vars.yml file:

exim_relay_enabled: false

Note that disabling exim-relay will stop email-notifications and other similar functions from working.

See this entry on the FAQ for other possible optimizations for a low-power server.

Installing

After configuring the playbook, run it with playbook tags as below:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

The shortcut commands with the just program are also available: just install-all or just setup-all

just install-all is useful for maintaining your setup quickly (2x-5x faster than just setup-all) when its components remain unchanged. If you adjust your vars.yml to remove other components, you'd need to run just setup-all, or these components will still remain installed. Note these shortcuts run the ensure-matrix-users-created tag too.

Troubleshooting

See this section on the role's documentation for details.