Autoconfig file reference

This page documents the structure of an autoconfig file. Autoconfig files help clients automatically detect a user's configuration based on their email address's domain, and are either hosted by Thunderbird's ISP database or by the service provider directly.

How to read this page

This page is intended as a technical reference to the autoconfig file format, and documents the structure of the XML elements that can be found in one.

The type of an XML element is either a simple type such as "string" or "number", or a more complex type. In this latter case, the complex type is documented in a section with the same name. If the complex type is made up of multiple values from either attributes or nested XML elements, those values are described in a table, which describes the location (attribute or child element), type and occurrence (how many times this attribute or child element can appear) for each of them.

This page does not include full examples of autoconfig files, though it's recommended to refer to files included in the ISP database repository as practical examples.

Autoconfig file structure

An autoconfig file is an XML file which describes the technical configuration relevant to a given service provider. Its top-level element is named clientConfig and has the following structure:

name	location	type	occurrence	description
version	attribute	string	1	The version string 1.1.
emailProvider	child	EmailProvider	1	The email service provider described in this file.

EmailProvider

This section documents the high-level configuration of an email service provider. Autoconfig files are expected to only feature a single emailProvider element.

name	location	type	occurrence	description
id	attribute	string	1	An arbitrary identifier for this provider. Typically its main domain.
domain	child	string	1-*	A domain covered by the provider.
displayName	child	string	1	The provider's human-readable name.
displayNameShort	child	string	1	A shorter version of the provider's human-readable name.
incomingServer	child	Server	1-*	A server configuration for receiving email.
outgoingServer	child	Server	1-*	A server configuration for sending email.
documentation	child	Documentation	1-*	A documentation page on the service provider's website.

Server

This section documents server configuration, which is the same for both incoming and outgoing server (except for the restrictions on the type attribute, see below).

A single autoconfig file may include multiple incomingServer and outgoingServer sections, even with the same type, in order to document multiple available configurations (e.g. with different ports or transport security methods). When this is the case, clients should consider each configuration in order, based on what it supports.

name	location	type	occurrence	description
type	attribute	ServerType	1	The protocol to use with the server.
hostname	child	PatternString	1	The server's hostname.
port	child	number	1	The server's port number.
socketType	child	SocketType	1	The transport security for the server.
username	child	PatternString	1	The username to use for authenticating on the server.
authentication	child	AuthMethod	1-*	The method for authenticating on the server.

ServerType

Describes the protocol to use with the server. Available types for incoming servers are:

• imap: the server uses IMAP
• pop3: the server uses POP
• exchange: the server uses one of the proprietary APIs to interact with Microsoft Exchange servers. Clients are expected to detect API support using one of Microsoft's auto-discovery APIs. Clients may reuse the configuration for an exchange incoming server as an outgoing server configuration (as Exchange APIs typically cover both receiving and sending email).

Available types for outgoing servers are:

• smtp: the server uses SMTP

PatternString

The hostname and username elements can either be set to a static value (e.g. imap.example.com or alice@example.com), or can be derived from the user's email address using placeholders.

Using placeholders is helpful for hostnames when multiple domains are configured for the same file, or for usernames to instruct what part of a user's email address should be used for authentication.

Supported placeholders are:

• %EMAILADDRESS%: the user's full email address
• %EMAILLOCALPART%: the part of the user's email address before the @ symbol
• %EMAILDOMAIN%: the part of the user's email address after the @ symbol

Below are a few examples, which all assume the the user's email address is alice@example.com:

<hostname>%EMAILDOMAIN%</domain> <!-- translates to "example.com" -->
<hostname>imap.%EMAILDOMAIN%</domain> <!-- translates to "imap.example.com" -->
<hostname>imap.example2.com</domain> <!-- translates to "imap.example2.com" -->
...
<username>%EMAILADDRESS%</domain> <!-- translates to "alice@example.com" -->
<username>%EMAILLOCALPART%</domain> <!-- translates to "alice" -->

SocketType

Describes the transport security for the server. Allowed values are:

• plain: no transport security (plain text)
• SSL: SSL/TLS
• STARTTLS: upgrade to TLS via STARTTLS

AuthMethod

Describes the authentication method for this server. A single server may include one or more authentication elements, in which case clients should consider them in order (e.g. if both OAuth2 and password authentication are included in that order, clients are expected to prioritize OAuth2 over password authentication if possible).

Allowed values are:

• password-cleartext: password authentication, with the password communicated in clear text
• password-encrypted: password authentication, with the password communicated in an obfuscated form (such as via CRAM-MD5 for IMAP, POP and SMTP)
• NTLM: NTLM authentication
• GSSAPI: Kerberos/GSSAPI authentication
• OAuth2: OAuth2 authentication
• none: no authentication needed

Documentation

A documentation element describes a page on the provider's website documenting the service and how to configure it with third-party clients.

name	location	type	occurrence	description
url	attribute	string	1	The page's URL.
descr	child	Description	0-*	A description of the page.

Description

A description element features a lang attribute, which value is the IETF language tag matching the description's language. The value of the descr element is a string, which contains a short human-readable description of the page (typically its title).