Author: Ben Bucksch

Thunderbird can automatically configure most mail accounts. Autoconfiguration makes it very easy for users to configure the connection of Thunderbird to their email servers. In many cases, people should be able to download and install Thunderbird, enter only their real name, email address and password in the account setup dialog, and have a fully functioning mail client, and get and send their mail as securely as possible.

This document describes how Autoconfiguration in Thunderbird works, and what to do to allow mail servers to be autoconfigured.

See also:

Mechanisms

Thunderbird gets the server settings via different means, each of which is intended for different cases:

All the lookup mechanisms use the email address domain as base for the lookup. For example, for the email address fred@example.com , the lookup is performed as (in this order):

  1. tb-install-dir/isp/example.com.xml on the harddisk
  2. check for autoconfig.example.com
  3. look up of "example.com" in the ISPDB
  4. look up "MX example.com" in DNS, and for mx1.mail.hoster.com, look up "hoster.com" in the ISPDB
  5. try to guess (imap.example.com, smtp.example.com etc.)

We may add DNS SRV records as supported mechanism in the future, but we currently do not.

How to add support for your domain

Classification

If you are a big ISP (> 100,000 users) providing email addresses solely under a few domains like "example.com" and "example.de", you may either submit the configuration to the ISPDB or set up a configuration server.

If you support email aliases and the user's login name is not part of the email address (for example, users may have "hero@example.com" as email address, but the IMAP/POP/SMTP login name is neither "hero" nor "hero@example.com", but "u67578"), you need to set up a configuration server, which does the email address -> login name lookup.

If you host customer domains, i.e. you are "hoster.com", but your customers have "fred@flintstone.com" and "louis@kent.com" as domains, with only a few users per domain, you need to set up a configuration server (or rely on DNS MX).

If you are a small company installing Thunderbird on your employees' desktops, you can place a configuration file in the Thunderbird installation folder.

ISPDB

Database URL is <https://autoconfig.thunderbird.net/v1.1/>, append domain name, e.g. <https://autoconfig.thunderbird.net/v1.1/freenet.de>.

Current process: File a bug in Bugzilla, Product "Webtools", Component "ISPDB Database Entries", with a configuration file that matches the requirements described below.  The component is actively watched for new bugs (as of November 2015) so there is no need to request review on the file.

Configuration server at ISP

Given the email address "fred@example.com", Thunderbird checks <https://autoconfig.example.com/mail/config-v1.1.xml?emailaddress=fred@example.com> (preferred) and <https://example.com/.well-known/autoconfig/mail/config-v1.1.xml> and the same URLs with http (see section SSL below). The results are used in this order of preference.

If possible, please use <https://autoconfig.example.com/mail/config-v1.1.xml?emailaddress=fred@example.com>.

Small company

If you are a small company, you can put the XML configuration file on your web server, at URL <https://example.com/.well-known/autoconfig/mail/config-v1.1.xml> pointing to an XML file.

Domain hoster

If you are an ISP that hosts domains for your customers - for example, you are hoster.com and your customer registers fancy.com or example.com, and your servers accept and serve the mail for example.com -, you should set up an autoconfig server.

DNS

For each customer domain, you add a DNS record (in addition to the existing MX, A www etc. DNS records):
autoconfig IN A 10.2.3.4
or
autoconfig IN CNAME autoconfig.hoster.com.
... where 10.2.3.4 and autoconfig.hoster.com are IP addresses / hostnames you own.
This allows Thunderbird to find you as hoster.

To make the Version without an autoconfig DNS Entry work you have to make sure that example.com points to the Webserver you will place the config-v1.1.xml on.

Example: example.com A 10.2.3.4

Web server

You set up a web server bound to a physical IP address. This may be on the same machine as other web servers, but the web server must be configured to the content to any requested domain.

You must use a virtual host that match all autoconfig.* domains of your customers. In Apache terms, you can use a "ip-based virtual host". In the Apache configuration files, that means something like: Listen 10.2.3.4:80 (of course, you use a public IP address that you own)

<VirtualHost 10.2.3.4:80> #Must be the first and only virtual host with this ip!
    DocumentRoot /var/www/autoconfig/
    ServerName autoconfig.hoster.com
    <Directory /var/www/autoconfig>
	Order allow,deny
	allow from all
    </Directory>
</VirtualHost>

Place the configuration file at the URL /mail/config-v1.1.xml on that host.

All config files must be served as Content-Type: text/xml (or application/xml), otherwise the file will be ignored. Also, they must use charset UTF-8 (esp. if there are any non-ASCII-characters).

If you like to use name-based virtual hosts you probably don't want to setup the autoconfig subdomain for every domain of your customers.
You can add a Rewriterule in the default virtual host (on debian /etc/apache2/sites-enabled/000-default)  to match all autoconfig.* subdomains:

<VirtualHost *:80> #Must be the first Virtual host
	ServerAdmin webmaster@hoster.com
	ServerName www
	DocumentRoot /var/www
	RewriteEngine On
	RewriteCond %{HTTP_HOST} ^autoconfig\. [NC]
	RewriteRule ^/(.*)	http://autoconfig.hoster.com/$1 [L,R=301,NE]
        #...
</VirtualHost>
<VirtualHost *:80>
    DocumentRoot /var/www/autoconfig/
    ServerName autoconfig.hoster.com
    <Directory /var/www/autoconfig>
 	Order allow,deny
	allow from all
    </Directory>
</VirtualHost>

If you use nginx, you can easily add a subdomain to all your Domains, which does the same as above. Either, you can redirect them to a common hostname:

server {
	listen 10.2.3.4:80; #use your server's public IP here!
	server_name autoconfig.*;
	return 301 http://autoconfig.hoster.com$request_uri;
}

Or serve them directly from a common directory:

server {
	listen 10.2.3.4:80; #again, use your server's public IP here!
	server_name autoconfig.*;
	location / {
		root /var/www/autoconfig;
	}
}

SSL

https was added in June 2019 to the spec. Please use https whenever possible. Former versions of this spec defined http only. http is still supported for existing hosts and in order to support domain hosters. http is deprecated now, but will need to be supported until at least end of 2023 for both of these reasons.

Configuration file

How to create a configuration file and the config file format definition