Thunderbird:Autoconfiguration:ConfigFileFormat

Author: Ben Bucksch. Please do not change this doc without checking with the author.

This page is the authorative specification of the config file that the Mozilla ISPDB and config services at ISPs return.

It is XML, with a clearly defined format, to be stable and usable by other mail clients, too. Update Aug 2010: In fact, Evolution and KMail and Kontact now use it, too.

Description

Some description

XML

The XML file must be called `config-v1.1.xml` and must be served under a specific path <https://example.com/.well-known/autoconfig/mail/config-v1.1.xml>.

<?xml version="1.0"?>
<clientConfig version="1.1">
    <emailProvider id="example.com">
      <domain>example.com</domain>
      <domain>example.net</domain>

      <displayName>Google Mail</displayName>
      <displayShortName>GMail</displayShortName>

      <incomingServer type="pop3">
         <hostname>pop.example.com</hostname>
         <port>995</port>
         <socketType>SSL</socketType>
           <!-- "plain": no encryption
                "SSL": SSL 3 or TLS 1 on SSL-specific port
                "STARTTLS": on normal plain port and mandatory upgrade to TLS via STARTTLS
                -->
         <username>%EMAILLOCALPART%</username>
            <!-- "password-cleartext",
                 "plain" (deprecated):
                          Send password in the clear
                          (dangerous, if SSL isn't used either).
                          AUTH PLAIN, LOGIN or protocol-native login.
                 "password-encrypted",
                 "secure" (deprecated):
                           A secure encrypted password mechanism.
                           Can be CRAM-MD5 or DIGEST-MD5. Not NTLM.
                 "NTLM":
                           Use NTLM (or NTLMv2 or successors),
                           the Windows login mechanism.
                 "GSSAPI":
                           Use Kerberos / GSSAPI,
                           a single-signon mechanism used for big sites.
                 "client-IP-address":
                           The server recognizes this user based on the IP address.
                           No authentication needed, the server will require no username nor password.
                 "TLS-client-cert":
                           On the SSL/TLS layer, the server requests a client certificate and the client sends one (possibly after letting the user select/confirm one), if available. (Not yet supported by Thunderbird)
                 "none":
                           No authentication
                  Compatibility note: Thunderbird 3.0 accepts only "plain" and "secure". It will ignore the whole XML file, if other values are given. -->
         <authentication>password-cleartext</authentication>
         <pop3>
            <!-- remove the following and leave to client/user? -->
            <leaveMessagesOnServer>true</leaveMessagesOnServer>
            <downloadOnBiff>true</downloadOnBiff>
            <daysToLeaveMessagesOnServer>14</daysToLeaveMessagesOnServer>
            <!-- only for servers which don't allow checks more often -->
            <checkInterval minutes="15"/><!-- not yet supported -->
         </pop3>
         <password>optional: the user's password</password>
      </incomingServer>

      <outgoingServer type="smtp">
         <hostname>smtp.googlemail.com</hostname>
         <port>587</port>
         <socketType>STARTTLS</socketType> <!-- see above -->
         <username>%EMAILLOCALPART%</username> <!-- if smtp-auth -->
            <!-- smtp-auth (RFC 2554, 4954) or other auth mechanism.
                 For values, see incoming.
                 Additional options here:
                 "SMTP-after-POP":
                     authenticate to incoming mail server first
                     before contacting the smtp server.
                  Compatibility note: Thunderbird 3.0 accepts only "plain",
                  "secure", "none", and "smtp-after-pop".
                  It will ignore the whole XML file, if other values are given.
            -->
         <authentication>password-cleartext</authentication>
            <!-- If the server makes some additional requirements beyond
                 <authentication>.
                 "client-IP-address": The server is only reachable or works,
                     if the user is in a certain IP network, e.g.
                     the dialed into the ISP's network (DSL, cable, modem) or
                     connected to a company network.
                     Note: <authentication>client-IP-address</>
                     means that you may use the server without any auth.
                     <authentication>password-cleartext</> *and*
                     <restriction>client-IP-address</> means that you need to
                     be in the correct IP network *and* (should) authenticate.
                     Servers which do that are highly discouraged and
                     should be avoided, see {{bug|556267}}.
                Not yet implemented. Spec (element name?) up to change.
            -->
         <restriction>client-IP-address</restriction>
         <!-- remove the following and leave to client/user? -->
         <addThisServer>true</addThisServer>
         <useGlobalPreferredServer>true</useGlobalPreferredServer>
         <password>optional: the user's password</password>
      </outgoingServer>

      <identity>
         <!-- needed? -->
         <!-- We don't want Verizon setting "Organization: Verizon"
              for its customers -->
      </identity>

      <!-- see description. Not yet supported, see bug 564043. -->
      <inputField key="USERNAME" label="Screen name"></inputField>
      <inputField key="GRANDMA" label="Grandma">Elise Bauer</inputField>

      <!-- Add this only when users (who already have an account) have to
           do something manually before the account can work with IMAP/POP or SSL.
           Note: Per XML, & (ampersand) needs to be escaped to & a m p ;
           (without spaces).
           Not yet implemented, see bug 586364. -->
      <enable
           visiturl="https://mail.google.com/mail/?ui=2&shva=1#settings/fwdandpop">
           <instruction>Check 'Enable IMAP and POP' in Google settings page</instruction>
           <instruction lang="de">Schalten Sie 'IMAP und POP aktivieren' auf der Google Einstellungs-Seite an</instruction>
      </enable>

      <!-- A page where the ISP describes the configuration.
           This is purely informational and currently mainly for
           maintenance of the files and not used by the client at all.
           Note that we do not necessarily use exactly the config suggested
           by the ISP, e.g. when they don't recommend SSL, but it's available,
           we will configure SSL.
           The text content should contains a description in the native
           language of the ISP (customers), and a short English description,
           mostly for us.
      -->
      <documentation url="http://www.example.com/help/mail/thunderbird">
         <descr lang="en">Configure Thunderbird 2.0 for IMAP</descr>
         <descr lang="de">Thunderbird 2.0 mit IMAP konfigurieren</descr>
      </documentation>

    </emailProvider>

    <!-- This allows to access the webmail service of the provider.
         The URLs are loaded into a standard webbrowser for the user.
         Specifying this is optional. -->
    <webMail>
      <!-- Webpage where the user has to log in manually by entering username
           and password himself.
           HTTPS required. -->
      <loginPage url="https://mail.example.com/login/" />

      <!-- Same as loginAutomaticDOM, but the website makes checks that
           the user comes from the login page. So, open the login page
           in the browser, get the page's DOM, fill out name and password
           fields for the user, and trigger the login button.
           The login button might not be an HTML button, just a div, so
           to trigger it, send a click event to it.
           HTTPS is required for the URL. -->
      <loginPageInfo url="https://mail.example.com/login/">
        <!-- What to fill into the usernameField.
             Format is the same as for <username> within <incomingServer>,
             including placeholders. See below for valid placeholders. -->
        <username>%EMAILADDRESS%</username>
        <!-- Allows to find the textfield on the page, to fill it out.
             The id attribute give the DOM ID,
             The name attribute give the DOM name attribute.
             One or both of id and name attributes must exist.
             Try the ID first (e.g. using getElementById()), if existing.
             Otherwise, try finding the element by name.
             Don't treat the IDs given in this XML file as trusted,
             but before using them, verify the format
             (e.g. only characters and digits for IDs).
             If you use powerful functions like jQuery, and the XML returns
             you code in the username ID, and you feed it unchecked to jQuery,
             it may be executed. -->
        <usernameField id="email_field" name="email" />
        <passwordField name="password" />
        <!-- The submit button to trigger the server submit
             after filling in the fields.
             id and name attributes: See <usernameField> -->
        <loginButton id="submit_button" name="login"/>
      </loginPageInfo>
    </webMail>

    <clientConfigUpdate url="https://www.example.com/config/mozilla.xml" />

</clientConfig>

Multiple servers

incomingServer and outgoingServer may appear several times. They are in order of priority, the first entry should generally be used, unless there's a specific factor or policy which prefers a later config.

For example, there may be configs with STARTTLS and normal SSL. Use the first entry listed. If that fails (server config change), you can try the second config. If IMAP and POP3 servers both exist, then both should be listed; the client or end user can select the protocol which best suits its needs. The config/ISP can, however, express a preference for IMAP or POP3 by what is listed first in the config file.

Placeholders

The email address (before @ or with domain) that the user entered can be used as placeholder in the config file, so the file is the same for all users (i.e. static).

Placeholders:

• %EMAILADDRESS% (full email address of the user, usually entered by the user)
• %EMAILLOCALPART% (email address, part before @)
• %EMAILDOMAIN% (email address, part after @)
• %REALNAME% (needed?)
• The key (surrounded by %) in <inputfield key=""> (see below)

These placeholders can be used as value or value part in most settings which take a string.

User input fields

(not yet implemented, see bug 564043)

For some ISPs, the IMPA/POP/SMTP username (and maybe other fields) has no relation to the email address and has to be entered separately. E.g. Email address is ben.bucksch@wong.com (chosen by user), but username is G675476 (provided by ISP).

In this case, an <inputfield> can be added for the username. It will let the client show a textfield to the user. The user-visible label is the one provided in the <inputfield label=""> attribute, to allow the ISP to use custom terminology for "username". The label is not localizable, that would be too complicated and most ISPs are local anyways - if really important, the ISP config server can look at the HTTP headers during the fetch.

The text that the user entered is written into a placeholder %KEY%, where KEY is the content of the <inputfield key="KEY"> attribute and must be only upper case letters. The placeholder can then be used in other settings, see #Placeholders above.

For example, a config file entry

        <userinput label="Username" key="%USERNAME%">D123456</userinput>

would result in a UI like:

  Username:     [             ] example: D123456

and cound be used elsewhere in the config file like:

        <username>%USERNAME%</username>

and if the user enters "D32198", it would be automatically filled in like:

        <username>D32198</username>

i.e. using D32198 as username for IMAP, POP or SMTP.

The system is generic, so that it can in theory be used for other values as well. No other such purpose is currently known, apart from a separate POP and SMTP username maybe. It should not be used to let the user supply hostnames, as that would defeat the purpose of the autoconfig and be worse than the manual config UI provided by the client.

TODO

• Values specific to IMAP, e.g. bug 558659 (special folders), bug 572465 (subfolders) etc.. However, most of these can and should be done as IMAP extensions.
• All settings and enum values
• In bug 849540 and bug 1166625, a new authentication type was added to support OAuth2 in gmail.com domains. This looks like:

    <incomingServer type="imap">
      <hostname>imap.googlemail.com</hostname>
      <port>993</port>
      <socketType>SSL</socketType>
      <username>%EMAILADDRESS%</username>
      <authentication>OAuth2</authentication>
      <authentication>password-cleartext</authentication>
    </incomingServer>

In Thunderbird 38 and later, this will choose OAuth2 as the preferred authentication method, supported in both imap and smtp. For Thunderbird prior to version 38, the OAuth2 entry will be ignored, and the fallback password-cleartext used instead.

The current status of OAuth2 does not allow this implementation to work for other providers, so additional parameters needed to specify this are hard-wired in Thunderbird. This mechanism will only work in gmail, other domains will fail if OAuth2 is specified. For the future, we would like to implement generic methods such that OAuth2 can be supported for arbitrary domains rather than requiring in-program customization for each supported domain.