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.

6 thoughts on “Mail client auto-configuration”

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

    Greetings
    Dennis

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

    1. Christoph Haas

      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.

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

    1. Christoph Haas

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

  3. Hello Christoph!
    Thanks to this great tutorial, I could manage to follow your guide and it works like a charm now 🙂 I learnt a lot from your tutorial.

    However 2 small errors occured:
    – Today I wanted to send an email to a posteo.org and delivery was refused because: “host mx01.posteo.de[185.67.36.61] refused to talk to
    me: 504 5.5.2 : Helo command rejected: need fully-qualified hostname”
    After some googling, I added another entry to /etc/hostname:
    ” webmail.example.com webmail” and changed in /etc/postfix/main.cf the value “myhostname” to the webmail.example.com
    -> This resolved the issue and sending to posteo.org succeeded, but I don’t know if this is technically correct?

    – Another minor issue was that I could not get the autoconfig to work.
    At first I added (as you described above) the vhost webmail.example.com-https.conf with your mentioned alias:
    “Alias /.well-known/autoconfig/mail /var/www/html/autoconfig-mail”, but the mail-client (thunderbird 102) failed to discover the settings.
    -> But by adding a vhost for “example.com” (only the domain, no subdomain!) with this alias just did the trick. Autoconfig now works perfectly fine 🙂

    Just wanted to share in case somebody else happens to come across these issues.

    1. change in /etc/hostname wrong/incomplete,
      correct:
      add entry ” webmail.example.com webmail”

Leave a Reply

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