Thunderbird Autoconfig for your own Mailserver

I was quite annoyed with Thunderbird’s autoconfig not working for my self-hosted Mailserver. Today I got to the point where I just invested some time into lookup up how to fix that. Since this took me like 10 minutes, I should’ve done this way earlier, and you should too.

How it works

Thunderbird actually offers multiple methods for its autoconfig^[1].
The probably most common one is a config-database with settings for the most common providers.
Thunderbird actually tells you when it is using this database, which is for example the case when logging in with Gmail or Microsoft.
The second option are DNS entries.
Honestly, I didn’t look too much into it, since the third option looked as if it can be done faster.

So, the third option is a .xml File, which is looked up when trying to add an account.
Lets assume, you try to add the account user@example.org, then Thunderbird will lookup a file stored under https://example.org/.well-known/autoconfig/mail/config-v1.1.xml.
Since I already have a webserver running under the domains I wanted to set this up for, I just needed to create this file and upload it to my webserver.

Later in this post, I will also explain how to do this with Hugo and Jekyll, since those two are the static site generators that I use for my websites.

Setting it up

So you need to create a file that is later hosted under https://example.org/.well-known/autoconfig/mail/config-v1.1.xml (obviously replace example.org with your domain, this can also be a subdomain).

<!-- This is used by Thunderbird. -->
<clientConfig version="1.1">

    <emailProvider id="my.domain">

        <domain>my.domain</domain>

        <incomingServer type="imap">

            <hostname>my.mail.server.de</hostname>
            <port>993</port>
            <socketType>SSL</socketType>
            <authentication>password-cleartext</authentication>
            <username>%EMAILADDRESS%</username>

        </incomingServer>

        <outgoingServer type="smtp">

            <hostname>my.mail.server.de</hostname>
            <port>465</port>
            <socketType>SSL</socketType>
            <authentication>password-cleartext</authentication>
            <username>%EMAILADDRESS%</username>

        </outgoingServer>

    </emailProvider>

</clientConfig>

Some comments about the options:

1. The emailProvider and domain seem to not matter too much, at least in my tests it didn’t make any difference whats stored in there.
   I accidentally didn’t change it after copying this file from one domain to another, and it still worked.
   Also, the documentation^[2] doesn’t say anything about those values (or I’m blind).
2. For the incoming and outgoing server, port and socket type need to be changed to what matches your setup. The values shown work with a default Mailcow Setup.
3. The authentication password-cleartext isn’t a problem as long as you're using encryption (this example uses SSL).
   password-cleartext is what you’d be using when choosing Password, normal in your client.
   Do not use this if the communication between Thunderbird and your server isn’t encrypted!
4. For some providers you need to pass the whole E-Mail Address as your Username, for some you only need the user part of the E-Mail Address.
   Change that according to your needs.
   Again, this setup works with a default Mailcow Setup. Other options are documented in the documentation^[2] under “Placeholders”.

The comment in the top is obviously not neccessary, but I left it in there to later remember why I have this file inside my .well-known folder, for this reason you should probably leave it in there aswell.

Hugo

In your main directory, you have a static/ directory. Just create the subfolders .well-known/autoconfig/mail/ in there (mkdir -p <directory> to automatically create missing subfolders), in which you store this config-v1.1.xml file. It will automatically be added to your generated site.

Jekyll

Create the subfolders .well-known/autoconfig/mail/ in your main website directory (mkdir -p <directory> to automatically create missing subfolders), in which you store this config-v1.1.xml file. Then, add a line with include: [".well-known"] to your _config.yml (or add the ".well-known" entry to an already existing include array).

Read more

For more information, check out these links from the official documentation:

1. About Thunderbird’s autoconfiguration in general
2. About the Autoconfig XML