Mail Autoconfig

3.1. XML config file

The following example shows the syntax of the XML config file returned.¶

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

    <displayName>Google Workspace</displayName>
    <displayShortName>GMail</displayShortName>

      <!-- type=
      "imap": IMAP
      "pop3": POP3
      "jmap": JMAP
      "ews": Microsoft Exchange Web Services
      "activesync": Microsoft ActiveSync
      -->
    <incomingServer type="imap">
      <hostname>imap.example.com</hostname>
      <port>993</port>
        <!--
        "plain": no encryption
        "SSL": TLS on TLS-specific port
        "STARTTLS": mandatory upgrade to TLS via STARTTLS
        -->
      <socketType>SSL</socketType>
        <!-- Authentication methods:
        "password-cleartext": SASL PLAIN, LOGIN or protocol-native login.
        "password-encrypted": SASL CRAM-MD5, DIGEST-MD5 etc. Not TLS.
        "NTLM": Deprecated Windows login mechanism
        "GSSAPI": Kerberos or Windows GSSAPI
        "TLS-client-cert": TLS client certificate on TLS layer
        "OAuth2": Must adhere to section "OAuth2 requirements".
        "none": No authentication

        Multiple <authentication> elements per server
        config are valid. Clients will pick the first
        one that they support.
        -->
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>

    <!-- You can have multiple incoming servers,
      and even multiple IMAP server configs.
      The first config is the preferred one, but the user or
      or client can choose the alternative configs. -->
    <incomingServer type="pop3">
      <hostname>pop.example.com</hostname>
      <port>995</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>

    <!-- Needed only for IMAP or POP3 -->
    <outgoingServer type="smtp">
      <hostname>smtp.googlemail.com</hostname>
      <port>587</port>
      <socketType>STARTTLS</socketType>
        <!-- smtp-auth (RFC 2554, 4954) or other auth mechanism. -->
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </outgoingServer>

    <incomingServer type="jmap">
      <url>https://jmap.example.com</url>
        <!-- Authentication methods
        "http-basic": RRFC 7661
        "http-digest"
        "OAuth2": Must adhere to section "OAuth2 requirements".
        -->
      <authentication>OAuth2</authentication>
      <authentication>http-basic</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>

    <incomingServer type="ews">
      <url>https://mail.example.com/EWS/Exchange.asmx</url>
      <username>%EMAILADDRESS%</username>
      <authentication>http-basic</authentication>
    </incomingServer>

    <incomingServer type="activesync">
      <url>https://mail.example.com/Microsoft-Server-ActiveSync</url>
      <username>%EMAILADDRESS%</username>
      <authentication>OAuth2</authentication>
    </incomingServer>

    <documentation url="http://www.example.com/help/mail/">
      <descr lang="en">Configure mail app for IMAP</descr>
      <descr lang="de">Email mit IMAP konfigurieren</descr>
    </documentation>

  </emailProvider>

  <addressbook type="carddav">
    <url>https://contacts.example.com/remote.php/dav</url>
    <authentication>http-basic</authentication>
    <username>%EMAILADDRESS%</username>
  </addressbook>

  <calendar type="caldav">
    <url>https://calendar.example.com/remote.php/dav</url>
    <authentication>http-basic</authentication>
    <username>%EMAILADDRESS%</username>
  </calendar>

    <!-- Upload files, allowing the user to share them.
    This can be used to send links instead of attachments,
    or to set up a file sync folder on the user's desktop.
    -->
  <fileShare type="webdav">
    <url>https://share.example.com/remote.php/dav</url>
    <authentication>http-basic</authentication>
    <username>%EMAILADDRESS%</username>
  </fileShare>

  <chatServer type="xmpp">
    <url>wss://example.com:5281/xmpp-websocket</url>
    <authentication>http-basic</authentication>
    <username>%EMAILADDRESS%</username>
  </chatServer>

  <chatServer type="xmpp">
    <hostname>xmpp.example.com</hostname>
    <port>5223</port>
    <socketType>TLS</socketType>
    <authentication>password-cleartext</authentication>
    <username>%EMAILADDRESS%</username>
  </chatServer>

  <videoConference type="opentalk">
    <url>https://talk.example.com/login</url>
    <authentication>OAuth2</authentication>
    <username>%EMAILADDRESS%</username>
  </videoConference>

    <!-- OAuth2 config for native public client apps.
    Gives e.g. clientID, expiry, and login page
    MUST adhere to "Open Client OAuth2 profile".
    -->
  <oAuth2>
    <authURL>https://login.example.com/auth</authURL>
    <tokenURL>https://login.example.com/token</tokenURL>
    <issuer>login.example.com</issuer>
    <scope>IMAP POP3 SMTP CalDAV CardDAV WebDAV offline_access</scope>
    <clientID>open</clientID>
    <!-- optional -->
    <clientSecret>give-me-your-password</clientSecret>
  </oAuth2>

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

</clientConfig>

3.2. Global elements

The file starts with an XML header, e.g. <?xml version="1.0"?>, and is encoded in UTF-8 without BOM.¶

<domain>example.com</domain>
<domain>example.net</domain>
<domain purpose="mx">example-hosting.com</domain>

<displayName>Google Workspace</displayName>
<displayShortName>GMail</displayShortName>

3.3. documentation

E.g.¶

<documentation url="http://www.example.com/help/mail/">
  <descr lang="en">Configure mail app for IMAP</descr>
  <descr lang="de">Email mit IMAP konfigurieren</descr>
</documentation>

This is purely informational and not required for the automatic setup.¶

Records the user help webpage at the provider that describes the mail server settings. The config may be based on that page, but does not necessarily have to match it, e.g. when a better config is available than the one described on the webpage.¶

The url property contains the URL of the webpage. The <descr> content describes the content and purpose of the page and why it's referenced here. Multiple <descr> elements with different lang properties are allowed, whereby the lang property contains the 2-letter ISO language code, like the HTML lang attribute.¶

3.4. Server sections

E.g. <incomingServer type="jmap"> or <calendar type="carddav">¶

• The type property specifies the wire protocol that this server uses. See section type below.¶

• <incomingServer> specifies the server that the mail client retrieves email from and submits changes to. In many protocols, this server is also used for sending email.¶

• <outgoingServer> is used for sending, if <incomingServer> does not support that directly. This is currently used only for SMTP in combination with IMAP and POP3.¶

• <incomingServer> and <outgoingServer> are within element <emailProvider>, whereas <calendar>, <addressbook>, <fileShare>, <chatServer> and <videoConference> are within the root element <clientConfig>, i.e. one level higher. Other than that, they work the same.¶

• In some protocols, the <incomingServer> server additionally provides calendars, addressbooks, and other data. For such protocols, the same server is not repeated in other specific server sections like <calendar>. Calendar-only clients supporting such multi-purpose protocols MUST read the <incomingServer> (nonewithstanding that it's within legacy element <emailProvider>) and test and use the parts of the protocol needed for their functionality.¶

3.5. type

The type property on the server section element specifies the wire protocol that this server uses.¶

Other protocol names can be added using an IANA registry. Their respective registrations need to define * the type name, as appearing in the type property * whether the protocol is URL-based or TCP-based, * which RFCs or document specifies the protocol, and * may define additional protocol-specific XML elements within the section and their meaning.¶

3.6. URL-based protocols

E.g.¶

<incomingServer type="jmap">
  <url>https://jmap.example.com/session</url>
  <authentication>http-basic</authentication>
  <username>%EMAILADDRESS%</username>
</incomingServer>

For server sections with protocols that are based on HTTPS or other URLs, the following elements are supported:¶

3.7. TCP-based protocols

For server sections with protocols that are based on TCP, the following elements are supported:¶

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

3.8. Placeholders

The <username> value may contain placeholders.¶

The following special substrings in the value MUST be replaced by the client, before the value is actually used.¶

Some clients MAY also support the same placeholders for the fields <hostname>, <url>, <authURL>, <tokenURL>, <issuer>, <displayName> and <displayShortName>.¶

3.9. XML validation

The client SHOULD validate that the config file is valid XML, and if the XML syntax is invalid, the client SHOULD ignore the entire file. In contrast, if there are syntactically valid, but unknown elements or properties, the client MUST NOT ignore the file.¶

The client SHOULD take only the elements and attributes that are supported by the client, and MUST ignore the others that are unknown to the client.¶

The client may optionally want to validate the XML before parsing it. This is not required. If the client choses to validate, the validation MUST ignore unknown elements and properties and MUST NOT drop or ignore a configuration that contains unknown elements and properties. This is needed to allow future extensions of the format without breaking existing clients.¶

4.1. Mail provider

First step is to directly ask the mail provider and allow it to return the configuration. This step ensures that the protocol is decentralized and the mail provider is in control of the configuration issued to mail clients.¶

• 1.1. https://autoconfig.%EMAILDOMAIN%/mail/config-v1.1.xml?emailaddress=%EMAILADDRESS% (Required. emailaddress is Optional)¶

• 1.2. https://%EMAILDOMAIN%/.well-known/autoconfig/mail/config-v1.1.xml (Optional)¶

• 1.3. http://autoconfig.%EMAILDOMAIN%/mail/config-v1.1.xml (Optional)¶

For example:¶

• 1.1. https://autoconfig.example.com/mail/config-v1.1.xml?emailaddress=fred@example.com¶

• 1.2. https://example.com/.well-known/autoconfig/mail/config-v1.1.xml¶

• 1.3. http://autoconfig.example.com/mail/config-v1.1.xml¶

Step 1.3. is mainly for legacy servers. Many current deployments use this HTTP URL.¶

4.2. Central database

The ISPDB contains the configurations for most mail providers with a market share larger than 0.1%, and contains configurations for half of the email accounts in the world.¶

This is a useful fallback for mail providers which do not host a config server described in the previous step. Using a central database (ISPDB) of mail configurations for the large mail providers will increase the success rate of finding a valid configuration drastically, up to 10-fold.¶

The mail client application may choose the mail config database provider. A public mail config database is available at base URL https://v1.ispdb.net/.¶

%ISPDB% below is the base URL of that database.¶

• 2.1. %ISPDB%%EMAILDOMAIN% (Recommended)¶

For example:¶

• 2.1. https://v1.ispdb.net/geologist.com¶

4.3. MX

Many companies do not maintain their own mail server, but let their email be hosted by a hosting company, which is then responsible for the email of dozens or thousands of domains. For these hosters, it may be difficult to set up the configuration server (step 1.1.) with valid TLS certificate for each of their customers, and to convince their customers to modify their root DNS specifically for autoconfig. On the other side, the ISPDB can only contain the hosting company and cannot know all their customers. To handle such domains, the protocol first needs to find the server hosting the email.¶

If the previous mechanisms yield no result, the client may perform a DNS MX lookup on the email domain, and retrieve the MX server (incoming email server) for that domain. Only the highest priority MX hostname is considered. From that MX hostname, 2 values are extracted:¶

• Extract only the second-level domain from the MX hostname, and use that as value for %MXBASEDOMAIN%. To determine the second-level domain, use the Public Suffic List or a similarly suited method, to correctly handle domains like ".co.uk" and ".com.au".¶

• Remove the first component from the MX hostname, i.e. everything up to and including the first ., and use that as value for %MXFULLDOMAIN%. Use it only if it is longer than %MXBASEDOMAIN%.¶

For example:¶

• For "mx.example.com", the MXFULLDOMAIN and MXBASEDOMAIN are both "example.com".¶

• For "mx.example.co.uk", the MXFULLDOMAIN and MXBASEDOMAIN are both "example.co.uk".¶

• For "mx.premium.europe.example.com", the MXFULLDOMAIN is "premium.europe.example.com" and the MXBASEDOMAIN is "example.com".¶

Then, attempt to retrieve the config for these MX domains, using the previous methods:¶

• 3.1. https://autoconfig.%MXFULLDOMAIN%/.well-known/mail-v1.xml?emailaddress=%EMAILADDRESS% (Required)¶

• 3.2. https://autoconfig.%MXBASEDOMAIN%/.well-known/mail-v1.xml?emailaddress=%EMAILADDRESS% (Recommended)¶

• 3.3. %ISPDB%%MXFULLDOMAIN% (Recommended)¶

• 3.4. %ISPDB%%MXBASEDOMAIN% (Recommended)¶

For example:¶

• 3.1. https://autoconfig.premium.europe.example.com/.well-known/mail-v1.xml?emailaddress=fred@example.com¶

• 3.2. https://autoconfig.example.com/.well-known/mail-v1.xml?emailaddress=fred@example.com¶

• 3.3. https://v1.ispdb.net/premium.europe.example.com¶

• 3.4. https://v1.ispdb.net/example.com¶

4.4. Local disk

For testing purposes, you may want to define a location on the disk, relative to the application installation directory, or relative to the user configuration directory, which may contain a configuration file for a specific domain, and which your application will use, if the above methods fail.¶

• 4.1. %USER_CONFIGURATION_DIR%/isp/%EMAILDOMAIN%.xml (Optional)¶

• 4.2. %APP_INSTALL_DIR%/isp/%EMAILDOMAIN%.xml (Optional)¶

For example:¶

• 4.1. /home/fred/.config/yourapp/isp/example.com.xml¶

• 4.2. /opt/yourapp/isp/example.com.xml¶

4.5. Other mechanisms

You may want to implement other mechanisms to find a configuration, for example Exchange AutoDiscover, DNS SRV, or heuristic guessing. If you implement such alternative methods, and if they are less secure than some of the mechanisms provided here, the alternative methods SHOULD be considered only with lower priority (as defined above) than the more secure mechanisms defined here. For evaluating other mechanisms, use similar criteria as outlined in section "Security considerations".¶

4.6. Manual configuration

If the above mechanisms fail to provide a working configuration, or if the user explicitly chooses so, you SHOULD give the end user the ability to manually enter a configuration, and use that configuration to configure the account.¶

5.1. User approval

Independent of the mechanisms used to find the configuration, before using that configuration, you SHOULD display that configuration to the end user and let him confirm it. While doing so:¶

• At least the second-level domain name(s) of the hostnames involved MUST be shown clearly and with high prominence.¶

• The client MUST NOT cut off parts of long second-level domains, to avoid spoofing. At least 63 characters MUST be displayed.¶

• Care SHOULD be taken with international characters that look like ASCII characters, but have a different code.¶

5.2. Login test

After the user confirmed the configuration, you SHOULD test the configuration, by attempting a login to each server configured. Only if the login succeeded, and the server is working, should the configuration be saved and retrieving and sending mail be started.¶

5.3. OAuth2 windows

If the configuration contains OAuth2 authentication, or any other kind of authentication that uses a web browser with URL redirects, you MUST show the full URL or the second-level domain of the current page to the end user, at all times, including after page changes, URL changes, or redirects. The authentication start URL may be the email hoster, but it redirects to a corporate server for login, and then back to the hoster. This allows for setups where the hoster is not allowed to see the plaintext passwords.¶

Showing the URL or hostname allows the end user to verify that he is logging in at the expected page, e.g. the login server of their company, instead of the email hoster's page.¶

6.1. Config location for single domain

The configuration file SHOULD be published at the URL for step 1.1., i.e.¶

• https://autoconfig.%EMAILDOMAIN%/.well-known/mail-v1.xml?emailaddress=%EMAILADDRESS%¶

e.g. for fred@example.com¶

• https://autoconfig.example.com/.well-known/mail-v1.xml?emailaddress=fred@example.com¶

For backwards compatibility with older mail clients, step 1.2. should also be implemented.¶

6.2. Config location for domain hosters

For mail providers which host entire domains for their business customers, the same URL as listed in the previous section is preferred.¶

Alternatively, the configuration file SHOULD be published at the location for step 3.1., i.e.¶

• https://autoconfig.%MXFULLDOMAIN%/.well-known/mail-v1.xml?emailaddress=%EMAILADDRESS%¶

E.g. if the MX server for customer domain example.net is "mx.premium.europe.example.com", then the config file should be at¶

• https://autoconfig.premium.europe.example.com/.well-known/mail-v1.xml?emailaddress=fred@example.net¶

For backwards compatibility with older mail clients, step 3.2. should also be implemented.¶

6.3. No authentication for config

Any of the above URLs for retrieving the config file MUST NOT require authentication, but MUST be public.¶

This is because the config contains the authentication method. Without knowing the config, the client does not know which authentication method is required and which username form (e.g. username "fred" or "fred@example.com" or "fred\EXAMPLE") to use. Given that the config is required for authentication, the config itself cannot require authentication.¶

6.4. Return config for non-existing email addresses

Servers SHOULD return a valid config, even if the email address sent as URL parameter does not exist. Otherwise, spammers or attackers would be able to test the validity of email addresses. This is true even if the config server needs the email address to determine which of multiple configurations is correct. In such a configuration, if the client sends a non-existing email address, the config server SHOULD return one of the valid configuations, so that valid and invalid email addresses are indistiguishable.¶

6.5. OAuth2 requirements

If OAuth2 is used, the OAuth2 server MUST adhere to the "Open Profile for Public Clients" or mAuth specification.¶

The OAuth2 server MUST either accept the public client ID as given in the config file, without secret, or MUST allow the string open as client ID, or both. The server MUST NOT employ any other methods to block clients that are acting on behalf of users.¶

The specifications also contain requirements for expiry times and the login page, which are needed for mail client applications to work.¶

The OAuth2 scope MUST include all services defined in this config file. The same refresh and access token MUST be valid for all services defined in the same config file, including for all URL-based protocols like CalDAV and all TCP-based protocols like IMAP.¶

8.1. DNSSEC

Due to their top-level domain, some domains do not have DNSSEC available to them, even if they would like to deploy it.¶

Even where the top-level domain supports it, DNSSEC is currently deployed in only 1% of domains, with adoption rates falling instead of rising, due to the difficulties of administrating it correctly.¶

Therefore, DNSSEC cannot be relied on in this specification, and DNS must be considered insecure for the purposes of this specification.¶

8.2. DNS SRV

DNS SRV protocols (RFC 2782, RFC 6186) are not used here, for 2 reasons:¶

1. DNS SRV relies on insecure DNS and the config can therefore be trivially spoofed by an attacker. See also DNSSEC above.¶

2. DNS SRV does not provide all the necessary configuration parameters. For example, we need all of:¶

• the username form ("fred@example.com", or "fred", or "fred\EXAMPLE", or even a username with no relation to the email address)¶

• authentication method (password, CRAM-MD5, OAuth2, SSL client certificate)¶

• authentication method parameters (e.g. OAuth parameters)¶

and other parameters. If any of these parameters are not configured right, the configuration won't work. While these parameters could theoretically be added to DNS SRV, that would mean a new specification and render the idea void that this is a protocol that already exists, is standardized and deployed. It is unlikely that all DNS SRV records would be updated with the new values. Therefore, it does not solve the problem.¶

This specification was created as an answer to these deficiencies and provides an alternative to DNS SRV.¶

8.3. CAPABILITIES

In the wild deployments from actual ISPs show that protocol-specific commands to find available authentication methods, e.g. IMAP CAPABILITIES or POP3 CAPA, are not reliable. Many email servers advertize authentication methods that do not work.¶

Some IMAP servers are default configured to list all SASL authentication methods that have corresponding libraries installed on the system, independent on whether they are actually configured to work. The client receives a long list of authentication methods, and many of them do not work. Additionally, the server response may be only "authentication failed" and may not indicate whether the method failed due to lack of configuration, or because the password was wrong. Because some authentication servers lock the account after 3 failed login attempts, and it may also fail due to unrelated reasons (e.g. username form, wrong password, etc.), the client cannot blindly issue countless login attempts. Locking the account must be avoided. So, simply attempting all methods and seeing which one works is not an option for the email client.¶

Additionally, some email servers advertize Kerberos / GSSAPI, but when trying to use it, the method fails, and also runs into a long 2 minute timeout in some cases. End users consider that to be a broken app.¶

Additionally, such commands are protocol specific and have to be implemented in multiple different ways.¶

Finally, some non-mail protocols may not support capabilties commands that include authentication methods.¶

9.1. Risk

If an attacker can provide a forged configuration, the provided mail hostname and authentication server can be controlled by the attacker, and the attacker can get access to the plain text password of the user. The attack can be implemented as man-in-the-middle, so the end user might receive mail as expected and never notice the attack.¶

An attacker gaining the plain text password of a real user is a very significant threat for the organization, not only because mail itself can contain sensitive information and can be used to issue orders within the organization that have wide-ranging impact, but given single-sign-on solutions, the same username and password may give access to other resources at the organization, including other computers or, in the case of admin users, even adminstrative access to the core of the entire organization.¶

Multi-factor authentication might not defend against such attacks, because the user may believe to be logging into his email and therefore comply with any multi-factor authentication steps required.¶

9.2. DNS

Any protocol that relies on DNS without further validation, e.g. http, should be considered insecure. This also applies to the DNS MX lookup and the https calls that base on its results, as described in section "MX".¶

One possible mitigation is to use multiple different DNS servers and verify that the results match, e.g. to use the native DNS resolver of the operating system, and additionally also query a hardcoded DoH (DNS over HTTPS) server.¶

Nonetheless, the result should be used with care. If such configs are used, the end user MUST explicitly confirm the config, particularly the resulting second-level domains. See section "User approval".¶

9.3. HTTP

HTTP requests may be intercepted, redirected, or altered at the network level. See "Risk" above.¶

Even if an http URL redirects to a https URL, and the domain of the https URL cannot be validated against the email domain, that is still insecure.¶

For that reason, clients MUST prefer HTTPS over HTTP during config retrieval, within the same retrieval method.¶

If such configs from HTTP are used, the end user MUST explicitly confirm the config, particularly the resulting second-level domains. See section "User approval".¶

9.4. Config updates

Part of the security properties of this protocol assume that the timeframe of possible attack is limited to the moment when the user manually sets up a new mail client. This moment is triggered by the end user, and a rare action - e.g. maybe once per year or even less, for typical setups -, so an attacker has limited chances to run an attack. While not a complete protection on its own, this reduces the risk significantly.¶

However, if the mail client does regular configuration updates using this protocol, this security property is no longer given. For regular configuration updates, the mail client MUST use only mechanisms that are secure and cannot be tampered with by an active attacker. Furthermore, the user SHOULD still approve config changes.¶

But even with all these protections implemented, the mail client vendor should make a security assessment for the risks of making such regular updates. The mail client vendor should consider that servers can be hacked, and most users simply approve changes proposed by the app, so these give only a limited protection.¶

9.5. Server security

Given that mail clients will trust the configuration, the server delivering it needs to be secure. Even though we call it "database", static configuration files that are generated before deployment in combination with a static web server offer better security and significantly better performance than dynamic queries from a database and responses generated on-the-fly on request. If a custom server is used, it SHOULD be updated regularly and hosted on a dedicated secure server with all unnecessary services and server features turned off.¶

Additions and modifications to the configurations are applicable to all respective users and must be made with care. The authenticity of the configuration MUST be verified from authorative sources. Server hostnames MUST be compared with the email domain names they are serving, and if they differ, the ownership of the server hostnames MUST be validated.¶

For these reasons, mail clients may use the public mail config database mentioned above.¶

The risk is mitigated to some degree by section "User approval".¶