Client Auto-Config for self-hosted Mail

Thunderbird, Outlook, Android & automx2

4 min readJan 31, 2022

Have you ever wondered, how to make your self hosted or corporate mail configure itself in Thunderbird, Android, IOs, Outlook and all those other clients out there? Well it’s easy, these clients look for a XML-configuration file at a specific web-location and configure accordingly. We will be using the python package automx2, which supports the protocols Mobileconfig (Apple), Autodiscover (Microsoft/Outlook) and Mozilla-Thunderbird’s Autoconfig, which doesn’t seem to be documented anywhere, but the obscure MDN content archive.

Setup automx2

Automx also has some implicit python dependencies not directly mentioned in the documentation. Install those alongside the package itself. As of writing this article I am using Debian 11 Bullseye. Install the relevant packages and create a new user for automx:

Requirements

Download and execute the setup-script from the automx GitHub-project, as the user you just created in it’s home directory:

Run Setupscript

Create a configuration file. It must be in the location ~/.automx2.conf . There is support for various other database backends, including MySQL, PostgreSQL and LDAP.

~/.automx2.conf

From the newly created home directory, run the following command to test your setup, if there are no errors, execute an HTTP-request to the /initdb-location, to initialize the database:

Run server and init db

Now you should be able to query the server for an auto-configuration file. In the example below, I also used xmllint from the Debian package libxml2-utils to format the output.

Autoconfig example

So, I will just mention this here: If you are a lazy person, you could just edit this file and put it into your public-facing web space at the same URL we got it from.

Otherwise we now have to configure automx, to return the correct server details, ports and supplemental information. The short version is:

define a ‘provider’ with a long and short name
define your servers, for example your IMAP and SMTP servers/ports
define a domain for your provider (one provider may have multiple domains)
link your IMAP and SMTP configuration to your domain (one domain may have multiple servers)

Database configuration

The second value you see in the ‘server’-table, is a priority. If you have backup servers for any of the protocols defined here, you may add them and assign a lower priority than the default server.

Run with System-D

In order to automatically run the server, we can create a systemd unit, start and enable it.

automx2.serivce

As you can see, the service is very straight forward, you may change the port or add addition ‘After’-directives if necessary.

Start and enable

Run behind Nginx

Since those configuration files are kind of important information, they should be encrypted during transmission. Some of the auto configuration protocols even require this (iOS), but it is not strictly necessary if you only use Thunderbird. If you don’t have a working Nginx reverse-proxy with TLS configured, read this article first and then come back here. The automx2 specific configuration is straight forward:

Nginx vServer example

The usage of the “autoconfig” and “autodiscover” subdomains can also be replaced by using the default domain and adding a “.well_known/autoconfig/” - location in the main server block.

Optional: If you do not want to use subdomains, add this to your main server-block. Mind the forward slash at the end of the “proxy_pass”-URL directive.

Test with a Mail Client

All that’s left to do now, is opening your favorite mail client and check if everything works.

In case it doesn’t work, Thunderbird is probably your best option for debugging. First, have the automx server running in an open console, so you are able to see the requests coming in.