Client Auto-Config for self-hosted Mail
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.
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:
Download and execute the setup-script from the automx GitHub-project, as the user you just created in it’s home directory:
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:
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.
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)
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.
As you can see, the service is very straight forward, you may change the port or add addition ‘After’-directives if necessary.
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:
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.
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.
Secondly, use the Thunderbird error console (Ctrl-Shift-J) to see the requests being sent on the client side.
Here you can also see the previously mentioned possibility of putting your configuration into a “.well_known” - location.
If you have any questions feel free to leave a comment.