[2019-12-24]

Mail client auto-configuration

Have you ever worked with Thunderbird as a mail client? When you add a mail account you get a 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 standard for it yet. Thunderbird has a couple of methods implemented.

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="example.org">
    <domain>example.org</domain>
    <displayName>My Crazy Mail Service</displayName>
    <displayShortName>CrazyMail</displayShortName>
    <incomingServer type="imap">
      <hostname>webmail.example.org</hostname>
      <port>143</port>
      <socketType>STARTTLS</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <incomingServer type="pop3">
      <hostname>webmail.example.org</hostname>
      <port>110</port>
      <socketType>STARTTLS</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <outgoingServer type="smtp">
      <hostname>webmail.example.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.

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.

Keep in mind that every domain you are hosting requires such an auto-configuration file. I’m confident that you find a way to generate those files automatically. 🙂

11 thoughts on “Mail client auto-configuration

  • 2019-12-30 at 03:03
    Permalink

    Killer pro tip! I didn’t realize you could do this autoconfig. Very helpful

    Reply
  • 2020-01-06 at 03:05
    Permalink

    Very handy
    Just %EMAILADDRESS% doesn’t work for me with Thunderbird 68.3.1.

    Reply
    • 2020-01-07 at 08:10
      Permalink

      That’s strange. Is the file pulled from your web server? Does Thunderbird say that it found any settings for your domain?

      Reply
      • 2020-01-07 at 23:43
        Permalink

        The file is pulled from the webserver and all the new account settings are filled out the way it should. Just not the username. It only shows the username instead of the emaiaddress.

        Reply
      • 2020-01-07 at 23:51
        Permalink

        Yes Thunderbird said it found configuration for the server.
        The email part was filled by me correctly too. It just is not showing at the username part there is only the inbox name, the part left from the @ sign. The @domain.tld part is not showing in the username thingy.

        Reply
          • 2020-01-08 at 12:53
            Permalink

            Apart from the obvious differences like domain names etc. my config-v1.1.xml looks exactly as yours. Thank you for sharing btw.

            Wen I test create a new gmail account in TB it works 100% the way it should. The username is the email address.

            Very strange indeed.

          • 2020-01-08 at 13:24
            Permalink

            The above tests was on Windows 10 system with Thunderbird 68.3.1.
            Wen I test on a Ubuntu 16.04 LTS system with Thunderbird 60.9 everything is exactly the same behavior.

          • 2020-01-08 at 14:32
            Permalink

            I created a autoconfig.domain.tld with the config-v1.1.xml.
            I removed all security headers.

            The behavior is still the same no email address in the username part just only the inbox. The lhs of the email is in the username part without the @domain.tld part.

            ????

  • 2020-02-08 at 19:15
    Permalink

    Hello Christoph, very nice feature!

    Reply
  • 2020-04-29 at 11:36
    Permalink

    This doesn’t work for me at all, I’ve tried everything!
    Placing it under various places both autoconfig.domain.org/mail/config etc or domain.org/.wellknown/autoconfig/mail and just every other variant. When I enter the url I can clearly see the config file, which I’ve tried to change multiple times. Nothing is working.
    DNS records, pointing to autoconfig.domain.org
    Can’t understand why it is not working.

    Reply

Leave a Reply to Christoph Haas Cancel reply

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