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:

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. 🙂

13 thoughts on “Mail client auto-configuration”

    1. Christoph Haas

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

      1. 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.

      2. 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.

          1. 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.

          2. 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.

          3. 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.

            ????

  1. 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.

  2. Hi,

    I’m a longtime user of your great ispmail tutorial. However, during some readings, I discovered RFC6186 that allows to define the IMAP and POP3 servers to be used for a domain.
    I think adding this part to your tutorial should make it a little better 😉
    Thanks again for this amazing job

  3. First thanks for this AMAZING tutorial!!!

    Just a quick note for anyone doing this. I run my web & mail servers on different hosts / ip’s so make sure you add this to your root example.org server where you host your webpages instead of on your emailserver.example.org where you are configuring your email server or the client(s) will never find it because it will be looking for it on the wrong server.

Leave a Reply

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

Scroll to Top