automx2: Email client configuration made easy

Autoconfig is a proprietary method developed by the Mozilla foundation. It was designed to configure a mail account within Thunderbird, and other email suites like Evolution and KMail have adopted the mechanism.

When a user begins to create a new mail account she is asked to enter her realname and mail address, e.g. alice@example.com. Thunderbird will then extract the domainpart (example.com) from the mail address and build a list of URIs to search for a configuration web service in the following order:

A configuration service such as automx2 listening on one of the listed URIs will receive the request, process it and respond with a set of configuration instructions.

Thunderbird will use the instructions to automatically fill in the required fields in the account. The only remaining task for the user is to confirm the settings. After that she can immediately start to use her new mail account.

Autodiscover is a proprietary method developed by Microsoft. The protocol version supported by automx2 was designed to configure a mail account within Outlook 2016 ff. Service lookups use the URLs shown below and, as a fallback option, DNS lookups. Please note that Microsft uses a different autodiscover mechanism for Office 365, which is not yet supported by automx2 because information about the technical details are not available free of charge.

All HTTP(S) queries send a POST request and submit XML which contains information about the account that should be configured. The DNS queries search for a CNAME resource record first, which is supposed to redirect the mail client to a resource outside of the mailbox owners domain, e.g. alice@example.com would be redirected to service.example-provider.com for configuration instructions. If the first DNS query fails the client may be redirected to a configuration service using a SRV RR like this:

The SRV RR used in the example above would send Alice’s client to service.example-provider.com and tell it to send the query to the configuration service on port 443.

Requests and responses use proprietary content types with an underlying property list format. automx2 will return unsigned data, which means that the service must be accessed via HTTPS only. Otherwise, your users have no way of knowing if they access the correct service and will be vulnerable to man-in-the-middle attacks.

To make configuration more convenient, automx2 supports Mozilla-style placeholders. For example, the string %EMAILADDRESS% in database records will be replaced with the email address specified during the query. While based on a proprietary feature of Autoconfig, automx2 also applies placeholders to Autodiscover and Mobileconfig responses.

The configuration file defines automx2 runtime behaviour and it specifies the backend automx2 should read mailbox account configuration data from.

During startup automx2 searches for runtime configuration instructions in the following locations. The first match will determine the configuration used.

To specify parameters and options automx2 uses an INI file syntax. The example configuration that ships with automx2 looks like this:

Place the content of the example configuration into one of the configuration locations automx2 looks for and adapt it to your needs. Then configure the database backend with data that suits your setup, as described below.

If you want to verify a vanilla installation of automx2 works, you can populate it with internal test data. Start automx2 as described in section Running automx2 and send the following request to populate your database:

This example assumes you are running automx2 on localhost listening on TCP port 4243, which is the suggested default port.

Once you have populated the database with sample data you can test if automx2 works. Use curl to send an account configuration request for user@example.com:

As shown in the example, make sure to quote the URL as necessary. Otherwise, your command shell might perform pattern matching for characters like the question mark ? (FISH does).

automx2 uses the SQLAlchemy toolkit to access databases. This allows a variety of databases, a.k.a. dialects, to be used, simply by defining the appropriate connection URL.

As mentioned in a previous section, you can use Alembic to create or upgrade your database. You need to start your first run using an empty database for this to work, because Alembic stores versioning information in said database. Database upgrades are based on this information. Follow the steps shown below, setting the RELEASE variable to the GitHub tag or release number of your choice.

Next, change the value for sqlalchemy.url in alembic.ini to match your automx2 configuration. Create an empty database unless you are using SQLite, in which case Alembic will create the database for you. The final steps are activating the automx2 virtual Python environment and invoke make.

You should see output similar to the following:

The following is an example for a OpenRC run script /etc/init.d/automx2 which I use for Gentoo Linux:

If you wish to override any of the settings, copy the following to /etc/conf.d/automx2 and uncomment/change variables according to your needs. This is purely optional.

If your system uses systemd you may want to deploy the following automx2.service unit file from the contrib section and place it in /etc/systemd/system/automx2.service:

Once you have installed the service you need to tell systemd to reload its list of available services:

It should now be able to tell you about a service named automx2:

Next enable and start automx2 using the following command:

You should see automx2 enabled and running:

You are now ready to start testing automx2, as described below.

While logged in as an unprivileged user, change into the installation directory and start the .venv/scripts/flask.sh launch script:

Now that automx2 is up and running, you need to configure the web server proxy that will receive requests from the outside and forwards them to automx2.

The following example defines a HTTP server, which will listen for requests to both autoconfig.example.com and autodiscover.example.com. All requests will be forwarded to automx2, which listens on TCP port 4243 in this example. Requests to /initdb are restricted to clients connecting from the local host. The proxy_set_header directives will cause NGINX to pass relevant data about incoming requests' origins.

The following example shows an Apache configuration similar to the one above. ProxyPreserveHost directives will cause apache to pass relevant data about incoming requests' origins.