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:


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">
    <displayName>Christoph's Mail Service</displayName>
    <incomingServer type="imap">
    <outgoingServer type="smtp">

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.

4 thoughts on “Mail client auto-configuration

  • 2021-12-28 at 01:11

    Moin Christoph,

    Both links to developer.mozilla.org (about the various methods for autoconf and for the XML syntax) are dead.

    The links to the ISPDB and the second link about the XML syntax at wiki.mozilla.org are still good.


    As always, this is a great tutorial! Thank you very much!

    • 2021-12-28 at 22:13

      Thanks, Dennis. I’m now linking to archive.org because I couldn’t see where they moved the files to. If anyone finds them please let me know.

  • 2022-06-05 at 08:03

    Hello Christoph, how can we configure autodiscover on outlook? Seems pretty undocumented, maybe you know something…

    • 2022-06-06 at 21:40

      I can’t tell for sure. But I assume that Micr0soft maintains their own database of domains for “common” mail service providers.


Leave a Reply

Your email address will not be published.