[2021-08-01]

Mail client auto-configuration

Have you ever worked with Thunderbird as a mail client? When you add a mail account you get a setup wizard like this:

You click on Continue and Thunderbird tries to find out which parameters are needed to connect to your mail server properly. But usually you just end up with this:

What is necessary to help Thunderbird (and other mail clients like Evolution, Kmail, Kontact or even Outl**k) with that? Unfortunately there is no official standard for it yet. But among other mail user agents Thunderbird has a couple of methods implemented to find out how the mail server for this domain can be reached.

For large ISPs they maintain their ISPDB database. But your market share may not be enough to be listed there. The next best option is to provide an XML file in a certain format through your web server. Thunderbird will look for this URL:

https://example.org/.well-known/autoconfig/mail/config-v1.1.xml

The syntax of the XML file is described here and here. A simple configuration file looks like this:

<?xml version="1.0" encoding="UTF-8"?>

<clientConfig version="1.1">
  <emailProvider id="workaround.org">
    <domain>workaround.org</domain>
    <displayName>Christoph's Mail Service</displayName>
    <displayShortName>ISPmail</displayShortName>
    <incomingServer type="imap">
      <hostname>webmail.workaround.org</hostname>
      <port>143</port>
      <socketType>STARTTLS</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <outgoingServer type="smtp">
      <hostname>webmail.workaround.org</hostname>
      <port>587</port>
      <socketType>STARTTLS</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </outgoingServer>
  </emailProvider>
</clientConfig>

I suggest putting this file into /var/www/html/autoconfig-mail/config-v1.1.xml and editing your Apache virtual host configuration (/etc/apache2/sites-enabled/webmail.example.org-https.conf) slightly:

Alias /.well-known/autoconfig/mail /var/www/html/autoconfig-mail

Try to load that URL /.well-known/autoconfig/mail/config-v1.1.xml from your domain in your web browser. At least Firefox and Chrome-based browsers validate the XML content automatically and tell you if you made a syntax mistake. No errors? Very good.

Obviously if you want to provide different settings for different domains then you need to create multiple configurations. In most setups the name of the mail server will probably be identical for all hosted domains.

Now next time you set up an account using Thunderbird (or other mail clients that support auto-configuration this way) your users will have a very pleasant quick way to add their email account. Try it out.

Leave a Reply

Your email address will not be published. Required fields are marked *