mailmaint B. Bucksch Internet-Draft Beonex Intended status: Informational 2 November 2026 Expires: 6 May 2027 Mail AutoConfig draft-ietf-mailmaint-autoconfig-07 Abstract This document describes a protocol that allows client applications to set up mail accounts and related services like calendar, contact and file sync, chat and video conference accounts, using only the email address and password. This existing protocol is used by service providers to publish the account configuration, so that client applications can find a working configuration automatically. The configuration is based on an email address, but is not limited to configuring email service. The running code and deployments documented here are in some cases no longer in line with security best-practices. Implementers are urged to study the security considerations attentively. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://benbucksch.github.io/autoconfig-spec/draft-ietf-mailmaint- autoconfig.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-mailmaint-autoconfig/. Discussion of this document takes place on the mailmaint Working Group mailing list (mailto:mailmaint@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/mailmaint/. Subscribe at https://www.ietf.org/mailman/listinfo/mailmaint/. Source for this draft and an issue tracker can be found at https://github.com/benbucksch/autoconfig-spec. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Bucksch Expires 6 May 2027 [Page 1] Internet-Draft autoconfig November 2026 Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 6 May 2027. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4 3. Data format . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. XML configuration file example . . . . . . . . . . . . . 5 3.2. Global elements . . . . . . . . . . . . . . . . . . . . . 7 3.2.1. clientConfig . . . . . . . . . . . . . . . . . . . . 7 3.2.2. emailProvider . . . . . . . . . . . . . . . . . . . . 7 3.2.3. domain . . . . . . . . . . . . . . . . . . . . . . . 8 3.2.4. displayName and displayShortName . . . . . . . . . . 9 3.2.5. documentation . . . . . . . . . . . . . . . . . . . . 9 3.2.6. oAuth2 . . . . . . . . . . . . . . . . . . . . . . . 10 3.3. Server sections . . . . . . . . . . . . . . . . . . . . . 11 3.3.1. Multiple server sections . . . . . . . . . . . . . . 12 3.3.2. type . . . . . . . . . . . . . . . . . . . . . . . . 12 3.4. URL-based protocols . . . . . . . . . . . . . . . . . . . 14 3.4.1. url . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.4.2. authentication . . . . . . . . . . . . . . . . . . . 14 3.4.3. username . . . . . . . . . . . . . . . . . . . . . . 15 3.5. TCP-based protocols . . . . . . . . . . . . . . . . . . . 15 3.5.1. hostname . . . . . . . . . . . . . . . . . . . . . . 16 Bucksch Expires 6 May 2027 [Page 2] Internet-Draft autoconfig November 2026 3.5.2. port . . . . . . . . . . . . . . . . . . . . . . . . 16 3.5.3. socketType . . . . . . . . . . . . . . . . . . . . . 16 3.5.4. authentication . . . . . . . . . . . . . . . . . . . 17 3.5.5. username . . . . . . . . . . . . . . . . . . . . . . 20 3.6. Placeholders . . . . . . . . . . . . . . . . . . . . . . 20 3.7. XML validation . . . . . . . . . . . . . . . . . . . . . 21 4. Configuration retrieval by mail clients . . . . . . . . . . . 21 4.1. Mail provider . . . . . . . . . . . . . . . . . . . . . . 22 4.1.1. Explanations for the URLs . . . . . . . . . . . . . . 23 4.1.2. Customizing the configuration for a specific user . . 23 4.2. Central database . . . . . . . . . . . . . . . . . . . . 24 4.3. MX . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.4. Local disk . . . . . . . . . . . . . . . . . . . . . . . 26 4.5. Other mechanisms . . . . . . . . . . . . . . . . . . . . 26 4.6. Manual configuration . . . . . . . . . . . . . . . . . . 27 5. Configuration validation . . . . . . . . . . . . . . . . . . 27 5.1. User approval . . . . . . . . . . . . . . . . . . . . . . 27 5.2. Login test . . . . . . . . . . . . . . . . . . . . . . . 27 5.3. OAuth2 windows . . . . . . . . . . . . . . . . . . . . . 27 5.4. OAuth2 client requirements . . . . . . . . . . . . . . . 28 6. Configuration publishing by mail providers . . . . . . . . . 28 6.1. Configuration location for a single domain . . . . . . . 29 6.2. Configuration location for domain hosters . . . . . . . . 29 6.3. No authentication for configuration . . . . . . . . . . . 30 6.4. OAuth2 server requirements . . . . . . . . . . . . . . . 30 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 7.1. Risk . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.2. DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.3. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 32 7.4. Configuration updates . . . . . . . . . . . . . . . . . . 32 7.5. Server security . . . . . . . . . . . . . . . . . . . . . 33 7.6. ISPDB . . . . . . . . . . . . . . . . . . . . . . . . . . 33 7.7. User testing with emailaddress . . . . . . . . . . . . . 33 7.8. Rate-limits . . . . . . . . . . . . . . . . . . . . . . . 33 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 8.1. Registration . . . . . . . . . . . . . . . . . . . . . . 33 8.2. Contents . . . . . . . . . . . . . . . . . . . . . . . . 34 8.3. Initial registration . . . . . . . . . . . . . . . . . . 34 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 9.1. Normative References . . . . . . . . . . . . . . . . . . 35 9.2. Informative References . . . . . . . . . . . . . . . . . 39 Appendix A. Alternatives considered . . . . . . . . . . . . . . 40 A.1. DNSSEC . . . . . . . . . . . . . . . . . . . . . . . . . 40 A.2. DNS SRV . . . . . . . . . . . . . . . . . . . . . . . . . 41 A.3. CAPABILITIES . . . . . . . . . . . . . . . . . . . . . . 41 Appendix B. Implementations . . . . . . . . . . . . . . . . . . 42 B.1. Clients . . . . . . . . . . . . . . . . . . . . . . . . . 42 B.2. Servers . . . . . . . . . . . . . . . . . . . . . . . . . 43 Bucksch Expires 6 May 2027 [Page 3] Internet-Draft autoconfig November 2026 Appendix C. RELAX NG schema . . . . . . . . . . . . . . . . . . 43 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 46 1. Introduction Configuring email, calendar and contacts client applications for a given user account at a specific service provider is often a tedious, error-prone and unnerving process. This document describes an automatic configuration protocol, originally defined in 2008 and in wide use since. As of 2026, about 80% of email accounts can be automatically configured using this protocol. The protocol works by first determining the domain from the email address, and then querying well-known URLs, which return the configuration parameters in computer-readable form. Failing that, various fallback sources can be applied, including a database of configurations for some major domains. While this protocol was originally conceived for configuring mail clients, it is also used for other kinds of services accessible to the user at the same provider, like calendar, contact and file sync, chat and video conference accounts. This document describes the AutoConfig protocol as it is used in the wild. Some of it, such as falling back to an HTTP URL, is not advisable from a security viewpoint. This document describes the protocol as compatible with running code, and another document will describe a potentially not backwards compatible process following today's best security practices. 2. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Data format Whether the ISP or a common central database returns the configuration, the resulting document MUST have the following data format and qualities. The format is in [XML]. The MIME type is text/xml. The sections below define the XML and its meaning. Most sections start with a concrete example of the elements that they define. Bucksch Expires 6 May 2027 [Page 4] Internet-Draft autoconfig November 2026 3.1. XML configuration file example The following example shows the syntax of the XML configuration file. example.com example.net Google Workspace GMail https://jmap.example.com OAuth2 Basic %EMAILADDRESS% imap.example.com 993 SSL password-cleartext %EMAILADDRESS% pop.example.com 995 Bucksch Expires 6 May 2027 [Page 5] Internet-Draft autoconfig November 2026 SSL password-cleartext %EMAILADDRESS% smtp.example.com 587 STARTTLS password-cleartext %EMAILADDRESS% https://mail.example.com/Microsoft-Server-ActiveSync %EMAILADDRESS% OAuth2 Configure mail app for IMAP Email mit IMAP konfigurieren https://contacts.example.com/remote.php/dav Basic %EMAILADDRESS% https://calendar.example.com/remote.php/dav Basic %EMAILADDRESS% https://share.example.com/remote.php/dav OAuth2 Basic %EMAILADDRESS% Bucksch Expires 6 May 2027 [Page 6] Internet-Draft autoconfig November 2026 wss://example.com:5281/xmpp-websocket Basic %EMAILADDRESS% https://talk.example.com/login OAuth2 %EMAILADDRESS% https://login.example.com https://login.example.com/auth https://login.example.com/token IMAP POP3 SMTP CalDAV CardDAV WebDAV offline_access open The formal grammar is in appendix RELAX NG schema. 3.2. Global elements The file starts with an XML header, e.g. , and is encoded in UTF-8 without BOM. 3.2.1. clientConfig The root element of the XML file is . The version is 1.2 for the version defined in this specification. 1.1 is a compatible previous version of this protocol: [AutoConfig1.1]. Higher versions are for future specifications. The client MUST NOT reject a configuration file solely based on the version number, and MUST accept configurations with an unknown version number that are otherwise adhering to this specification. 3.2.2. emailProvider Example: Bucksch Expires 6 May 2027 [Page 7] Internet-Draft autoconfig November 2026 RELAX NG: emailProvider = element emailProvider { attribute id { text }, ( domain | displayName | displayShortName | documentation | incomingServer | outgoingServer )* } Element is within the root element. The id is a unique string that typically matches the primary domain of the provider. The syntax of the ID is the same as for domain and hostname. Within are , and , , and . 3.2.3. domain Example: example.com example.net example-hosting.com RELAX NG: domain = element domain { attribute purpose { text }?, # the only defined value is "mx" text } The content of the element defines which email addresses this configuration is valid for. For example, a configuration with example.com is valid for email address fred@example.com. Multiple elements may be included, which means that the configuration is valid for all of these domains. Their order has no meaning - they may be sorted by number of users, importance to the provider, or alphabetically. Bucksch Expires 6 May 2027 [Page 8] Internet-Draft autoconfig November 2026 specifies the domain name of the MX server of this provider. It is used during the configuration file lookup using MX server names, as specified in MX _MX_. If the email address that is to be configured has an MX server that is within the domain given by , then this configuration is applicable for that email address. Adding the purpose attribute is RECOMMENDED. 3.2.4. displayName and displayShortName Example: Google Workspace GMail RELAX NG: displayName = element displayName { text } displayShortName = element displayShortName { text } Both elements may be used to display the provider or account name by the mail client UI, which therefore has expectations on length and expressiveness. The element contains the name of the provider, e.g. as preferred by the marketing of the provider itself. It should be no longer than 30 characters, to be meaningful to the user and to fit in the UI fields. The element contains the name of the provider, as typically used by end users. It should be no longer than 12 characters. It may be used by the mail client as base for the account name, and during everyday use of the app to represent the account, so it should be short, distinctive and represent the provider in the way end users refer and think of it. The mail client might concatenate either value with the email address, so these values should not be the email address. 3.2.5. documentation Example: Configure mail app for IMAP Email mit IMAP konfigurieren RELAX NG: Bucksch Expires 6 May 2027 [Page 9] Internet-Draft autoconfig November 2026 documentation = element documentation { attribute url { text }, descr* } descr = element descr { attribute lang { text }?, # 2-letter ISO language code text } This is purely informational and not required for the automatic setup. This element contains the end-user help webpage at the provider that describes the mail server settings. The configuration may be based on that page, but does not necessarily have to match it, e.g. when a better configuration is available than the one described on the webpage. The url attribute contains the URL of the webpage. The content describes the content and purpose of the page and why it's referenced here. Multiple elements with different lang attributes are allowed, whereby the lang attribute contains the 2-letter ISO language code, like the HTML lang attribute. 3.2.6. oAuth2 Example: https://login.example.com https://login.example.com/auth https://login.example.com/token IMAP POP3 SMTP CalDAV CardDAV WebDAV offline_access open RELAX NG: oAuth2 = element oAuth2 { ( authURL | tokenURL | issuer | scope | clientID | clientSecret )* } authURL = element authURL { text } tokenURL = element tokenURL { text } issuer = element issuer { text } scope = element scope { text } clientID = element clientID { text } clientSecret = element clientSecret { text } Element is within the root element. Bucksch Expires 6 May 2027 [Page 10] Internet-Draft autoconfig November 2026 It contains all necessary information to find and contact the OAuth2 authentication server to get an auth token, which can be used to log in directly to the servers marked with OAuth2 See OAuth2 server requirements and OAuth2 client requirements. 3.3. Server sections , etc. RELAX NG: serverSection = attribute type { text }, # see the IANA registry ( url | hostname | port | socketType | authentication | username )* incomingServer = element incomingServer { serverSection } outgoingServer = element outgoingServer { serverSection } calendar = element calendar { serverSection } addressbook = element addressbook { serverSection } fileShare = element fileShare { serverSection } chatServer = element chatServer { serverSection } videoConference = element videoConference { serverSection } setupServer = element setupServer { serverSection } * The type attribute specifies the wire protocol that this server uses. See type below. * 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. * is used for sending, if does not support that directly. This is currently used only for SMTP in combination with IMAP and POP3. * and are within element , whereas , , , , and are within the root element , i.e. one level higher. Other than that, they work the same. * In some protocols, the server additionally provides calendars, addressbooks, and other data. For such protocols, the same server is not repeated in other specific Bucksch Expires 6 May 2027 [Page 11] Internet-Draft autoconfig November 2026 server sections like . Calendar-only clients supporting such multi-purpose protocols MUST read the (notwithstanding that it's within legacy element ) and test and use the parts of the protocol needed for their functionality. 3.3.1. Multiple server sections Server sections of the same type (like or ) may appear multiple times in the same configuration file. In this case, they are listed in the order of preference by the configuration provider. The client should pick the first configuration that matches the client's requirements. The client may choose a different order or ignore some configurations, because * the client doesn't support a higher-priority protocol, e.g. a JMAP configuration is listed first and is the most preferred, but the client does not support JMAP yet, or * the client doesn't support a configuration setting, e.g. it doesn't support STARTTLS, or the configuration specifies only an OAuth2 authentication and the client either doesn't implement OAuth2, or there is a problem in the OAuth2 flow with this provider, or * the client has a specific policy to prefer another configuration, e.g. a STARTTLS configuration is listed before a direct TLS configuration, and the client has a policy of preferring direct TLS, or likewise the client prefers IMAP over POP3. Server types, elements and protocols that the client does not support MUST be ignored and the client MUST continue to parse the other server sections, which may contain configs that the client understands and supports. The client ignores the file only if there is no supported and working configuration found. 3.3.2. type The type attribute on the server section element specifies the wire protocol that this server uses. Bucksch Expires 6 May 2027 [Page 12] Internet-Draft autoconfig November 2026 +================+===========+====+===========+===================+ | Element |Type |Base|Name | Specification | +================+===========+====+===========+===================+ | incomingServer |jmap |URL |JMAP | [JMAP-Core], | | | | | | [JMAP-Mail], | | | | | | [JMAP-WebSocket], | | | | | | [JMAP-Contacts] | | | | | | et al | +----------------+-----------+----+-----------+-------------------+ | incomingServer |imap |TCP |IMAP | [IMAP4rev2] or | | | | | | [IMAP4rev1], et | | | | | | al | +----------------+-----------+----+-----------+-------------------+ | incomingServer |pop3 |TCP |POP3 | [POP3], | | | | | | [POP3-SASL] | +----------------+-----------+----+-----------+-------------------+ | outgoingServer |smtp |TCP |SMTP | [SMTP], [EMail] | +----------------+-----------+----+-----------+-------------------+ | calendar |caldav |URL |CalDAV | [CalDAV] | +----------------+-----------+----+-----------+-------------------+ | addressbook |carddav |URL |CardDAV | [CardDAV] | +----------------+-----------+----+-----------+-------------------+ | fileShare |webdav |URL |WebDAV | [WebDAV] | +----------------+-----------+----+-----------+-------------------+ | chatServer |xmpp |URL |XMPP | [XMPP], | | | | | | [XMPP-IM], | | | | | | [XMPP-WebSocket] | +----------------+-----------+----+-----------+-------------------+ | chatServer |xmpp-tcp |TCP |XMPP | [XMPP], [XMPP-IM] | +----------------+-----------+----+-----------+-------------------+ | chatServer |matrix |URL |Matrix | [Matrix] | +----------------+-----------+----+-----------+-------------------+ | setupServer |managesieve|TCP |ManageSieve| [ManageSieve], | | | | | | [Sieve] | +----------------+-----------+----+-----------+-------------------+ | incomingServer |ews |URL |Exchange | | | | | |Web | | | | | |Services | | +----------------+-----------+----+-----------+-------------------+ | incomingServer |activesync |URL |ActiveSync | | +----------------+-----------+----+-----------+-------------------+ | incomingServer |graph |URL |Microsoft | | | | | |Graph | | +----------------+-----------+----+-----------+-------------------+ Table 1 Bucksch Expires 6 May 2027 [Page 13] Internet-Draft autoconfig November 2026 Other protocol names can be added using an IANA registry. See the corresponding section below. 3.4. URL-based protocols https://jmap.example.com/session Basic %EMAILADDRESS% For server sections with protocols that are based on HTTPS or other URLs, the following elements are supported: 3.4.1. url Example: https://jmap.example.com/session RELAX NG: url = element url { text } The content of the element contains the [URL] where to contact the server. The URL scheme will normally be HTTPS and the URL starts with https:// ([HTTP], Section 4.2.2). Some protocols may use other schemes, e.g. WebSockets wss:// ([WebSocket], Section 3). 3.4.2. authentication Examples: OAuth2 Basic RELAX NG: authentication = element authentication { attribute system { text }?, # "http" or "sasl" text } The content of the element defines which HTTP authentication method to use. The system="http" attribute signals that the value refers to a WWW-Authenticate mechanism. Bucksch Expires 6 May 2027 [Page 14] Internet-Draft autoconfig November 2026 * Basic: Authenticate to the HTTP server using WWW-Authenticate: Basic. See [HTTP-Basic-Auth]. * Digest: Authenticate to the HTTP server using WWW-Authenticate: Digest. See [HTTP-Digest-Auth] * NTLM: Legacy Windows login mechanisms NTLM or NTLMv2, potentially with a Negotiate before. * OAuth2: Authenticate to the HTTP server using WWW-Authenticate: Bearer. See [OAuth2], Section 3. The provider MUST adhere to the requirements defined in OAuth2 server requirements. Note: The XML element for OAuth2 is OAuth2 without system attribute. Bearer is invalid. The rules as specified in Multiple authentication alternatives and Authentication verification and fallback apply here as well. 3.4.3. username Examples (alternatives): %EMAILADDRESS% fred RELAX NG: username = element username { text } The username to use for the authentication method. Placeholders MUST be replaced before using the actual value. See Placeholders. 3.5. TCP-based protocols For server sections with protocols that are based on TCP, the following elements are supported: imap.example.com 993 SSL password-cleartext %EMAILADDRESS% Bucksch Expires 6 May 2027 [Page 15] Internet-Draft autoconfig November 2026 3.5.1. hostname Example: imap.example.com RELAX NG: hostname = element hostname { text } The content of the element contains the fully qualified hostname of the server. 3.5.2. port Example: 993 RELAX NG: port = element port { xsd:positiveInteger } # TCP port, 1-65535 The content of the element is an integer and contains the TCP port number at the hostname. The port is typically specific to the combination of the wire protocol and socketType. 3.5.3. socketType Example: SSL RELAX NG: socketType = element socketType { text } The content of the element specifies whether to use direct TLS, STARTTLS, or none of these. * SSL: Directly contact the TCP port using TLS. TLS version 1.2 [TLSv1.2] or higher SHOULD be used. Higher versions may be required based on security situation, server support, and client policy decisions. * STARTTLS: Contact the TCP port first using an unencrypted plain socket, then upgrade to TLS using the protocol-specific STARTTLS specification [STARTTLS]. With this configuration, STARTTLS MUST Bucksch Expires 6 May 2027 [Page 16] Internet-Draft autoconfig November 2026 be used and TLS MUST be used after the STARTTLS upgrade. If the upgrade to TLS fails for whatever reason, the client MUST disconnect and MUST NOT try to authenticate. This prevents downgrade attacks that could otherwise steal passwords, user data, and impersonate users. * plain: Unencrypted connection, with neither TLS nor STARTTLS. May be needed for local servers. Deprecated. 3.5.3.1. TLS validation In all cases where TLS is used, either directly or using STARTTLS, the client MUST validate the TLS certificate and ensure that the certificate is valid for the hostname given in this configuration. If not, or if the TLS certificate is otherwise invalid, the client MUST either disconnect or MAY warn the user of the dangers and ask for user confirmation. Such fallback with warning and confirmation is allowed only at original configuration and MUST NOT be allowed during normal everyday connection. If the server had a valid TLS certificate during original configuration and the TLS certificate is later invalid during normal connection, the client MUST disconnect. As an exception, if the problem is that the TLS certificate expired recently, the client MAY choose to not consider that a failure during normal connection and MAY use other recovery mechanisms. 3.5.4. authentication Example: password-cleartext RELAX NG: authentication = element authentication { attribute system { text }?, # "http" or "sasl" text } The content of the element defines which authentication method to use. This can be either an authentication defined by the wire protocol, or a SASL scheme, or a successor to SASL. Bucksch Expires 6 May 2027 [Page 17] Internet-Draft autoconfig November 2026 * password-cleartext: Send password in the clear. Uses either the native authentication method defined by the wire protocol (if that is based on plaintext passwords), or a SASL authentication scheme like SASL PLAIN or SASL LOGIN, or a successor. * password-encrypted: An encrypted or hashed password mechanism. Includes SASL CRAM-MD5 [CRAM-MD5], DIGEST-MD5 [DIGEST-MD5], SCRAM- SHA-256-PLUS [SCRAM], and successors. TLS by itself does not qualify as password-encrypted. * NTLM: Legacy Windows login mechanisms NTLM or NTLMv2. * GSSAPI: [Kerberos] or [GSSAPI], a single sign-on mechanism based on TCP. * TLS-client-cert: On the SSL/TLS layer, after server request, the client sends a TLS client certificate for the user, possibly after letting the user select or confirm it. Uses SASL EXTERNAL scheme [SASL], Appendix A. * OAuth2: SASL OAUTHBEARER [SASL-OAuth2] (current) or XOAUTH2 (deprecated) or successors. The provider MUST adhere to the requirements defined in OAuth2 server requirements. * client-IP-address: The server can be used without any explicit authentication, and the client is admitted based on its IP address. This may be the case for some SMTP servers on local networks. Not supported on the Internet. Deprecated, because it breaks mobile devices. 3.5.4.1. Recommending specific SASL schemes Example: SCRAM-SHA-256-PLUS A specific SASL scheme [SASL] MAY be specified using the specific SASL authentication scheme name, e.g. SCRAM-SHA-256-PLUS [SCRAM]. To signal that, the element MUST have the system attribute set to value sasl, i.e. . In such a case, the server configuration section should also specify a more generic authentication mechanism as a lower priority alternative. Clients that support the specific authentication mechanism will use that, and other clients will use the more generic authentication mechanism. Without such fallback, the latter clients would fail. Bucksch Expires 6 May 2027 [Page 18] Internet-Draft autoconfig November 2026 3.5.4.2. Multiple authentication alternatives The element may appear multiple times within a server section. In this case, they are ordered from the most to the least preferred method, based on the policy of the provider. If a client does not support a specific authentication scheme, or does not have the conditions to use it, e.g. the client does not have a Client ID for this OAuth2 server, then the client MUST skip this element and use the next in the list instead. If none of the authentication methods are supported by the client, the client MUST ignore that server section and use the remaining server sections. 3.5.4.3. Authentication verification and fallback The client should test the configuration during setup, with an actual authentication attempt. If the authentication fails, the client decides based on the authentication error code how to proceed. For example, if the authentication method itself failed, or the error code indicates a systemic failure, the client should use a lower-priority authentication method from the list. If the authentication method is working, but the error code indicated that the username or password was wrong, then the client MAY ask the user to correct the password. For that reason, the server should be specific in the error codes and allow the client to distinguish between * an unsupported or non-working authentication method or other systemic failures * the client being rejected by the server * the user being blocked from login * the user authentication failing due to wrong password or username * other reasons If the server were to return the same error code for all these cases, the client might tell the user that the password is wrong, and the user starts attempting other passwords, potentially revealing passwords to other higher-value assets, which is highly dangerous. Bucksch Expires 6 May 2027 [Page 19] Internet-Draft autoconfig November 2026 If the authentication succeeded, the client MUST remember the working configuration and use that for all subsequent connections, until an explicit reconfiguration occurs. During normal everyday operation, the client SHOULD NOT fall back nor attempt multiple different authentication methods. See Configuration updates for the reasons. 3.5.5. username Examples (alternatives): %EMAILADDRESS% fred RELAX NG: username = element username { text } The username to use for the authentication method. Placeholders MUST be replaced before using the actual value. See next Placeholders. 3.6. Placeholders The value may contain placeholders. The following special substrings in the value MUST be replaced by the client, before the value is actually used. +==================+===========================+==================+ | Placeholder | Replace with | Example | +==================+===========================+==================+ | %EMAILADDRESS% | Email address of the user | fred@example.com | +------------------+---------------------------+------------------+ | %EMAILLOCALPART% | Part before @ in the | fred | | | email address | | +------------------+---------------------------+------------------+ | %EMAILDOMAIN% | Part after @ in the email | example.com | | | address | | +------------------+---------------------------+------------------+ Table 2 Some clients MAY also support the same placeholders for the fields , , , , , and . Bucksch Expires 6 May 2027 [Page 20] Internet-Draft autoconfig November 2026 3.7. XML validation If the XML syntax is invalid, the client MUST ignore the entire file. In contrast, if there are merely unknown elements or attributes, the client MUST NOT ignore the file. The client MUST disregard those elements, attributes and values that it does not support. The presence of unknown elements, attributes or values MUST NOT result in an error. Instead, they are simply ignored and treated as if they don't exist. Compare the rules for elements in Multiple authentication alternatives. If a server section then becomes invalid due to missing information, only that server section is ignored and the other server sections will still be processed. Only if no valid configuration is found in the document, the document as a whole is ignored, but other retrieval mechanisms might produce a different document with a valid configuration. This allows future extensions of the format without breaking existing clients. The RELAX NG schema is written to follow these rules: it accepts unknown elements, attributes, attribute values and element values, so that a validator does not reject a document merely because it uses extensions not defined here. 4. Configuration retrieval by mail clients The mail client application, when it needs the configuration for a given email address, will perform several steps to retrieve the configuration from various sources. The steps are ordered by priority. They may all be requested at the same time, but a higher priority result that is available should be preferred over a lower priority one, even if the lower priority one is available earlier. Exceptions apply when a higher priority result is either invalid or outdated, e.g. it doesn't work anymore, or the fetch method is less secure, according to the client's assessment. Lower priority requests MAY be cancelled, if a valid higher priority result has been successfully received. The priority is expressed below with the number before the URL or location, with lower numbers meaning higher priority, e.g. 1.2 has higher priority than 4.1. Bucksch Expires 6 May 2027 [Page 21] Internet-Draft autoconfig November 2026 In the URLs below, %EMAILADDRESS% SHALL be replaced with the email address that the user entered and wishes to use, and %EMAILDOMAIN% SHALL be replaced with the email domain extracted from the email address. For example, for fred@example.com, the email domain is example.com, and for fred@test.cs.example.net, the email domain is test.cs.example.net. For full support of this specification in clients, all "Required" and "Recommended" mechanisms MUST be implemented and working. For partial support of this specification in clients, all "Required" mechanisms MUST be implemented and working, and in this case, the implementor SHALL make explicit when advertising or referring to AutoConfig that there is only partial support of this specification. In servers, at least URL 1.1. MUST be implemented and working. If the email address parameter is not passed by the client, the server MUST return a configuration that works for all accounts or at least for a large part of accounts. 4.1. Mail provider The 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%/.well-known/client- autoconfig.xml?emailaddress=%EMAILADDRESS% (Required) * 1.2. https://autoconfig.%EMAILDOMAIN%/mail/config- v1.1.xml?emailaddress=%EMAILADDRESS% (Deprecated, but deployed) * 1.3. https://%EMAILDOMAIN%/.well-known/autoconfig/mail/config- v1.1.xml (Deprecated, but deployed) * 1.4. http://autoconfig.%EMAILDOMAIN%/mail/config-v1.1.xml (Deprecated, but deployed) The emailaddress URL parameter is Optional. For example: * 1.1. https://autoconfig.example.com/.well-known/client- autoconfig.xml?emailaddress=fred@example.com * 1.2. https://autoconfig.example.com/mail/config- v1.1.xml?emailaddress=fred@example.com Bucksch Expires 6 May 2027 [Page 22] Internet-Draft autoconfig November 2026 * 1.3. https://example.com/.well-known/autoconfig/mail/config- v1.1.xml * 1.4. http://autoconfig.example.com/mail/config-v1.1.xml 4.1.1. Explanations for the URLs URL 1.1. follows [RFC8615] for well-known URLs. Servers adhering to this version of the specification MUST support URL 1.1 and MUST have a valid TLS certificate for that hostname. URLs 1.2., 1.3. and 1.4. were used in the original protocol from around 2008, before [RFC8615] and predecessors existed. URL 1.4. is used by many current deployments, particularly email hosting companies that use DNS CNAME to redirect the customer email domain to a central provider AutoConfig server, which has a TLS certificate only for the provider domain and not every customer domain. Although HTTP is insecure, a large number of existing domains use it at the time of this writing, and ignoring it may lead to no result for many domains. Implementors need to balance this risk with the alternatives like guessing hostnames or users searching the Internet. Security Considerations contains more detail on what an implementor needs to consider. 4.1.2. Customizing the configuration for a specific user To allow the mail provider to return a configuration adjusted for that mailbox, the client sends the email address as query parameter in URL 1.1. For example, a global company might want to locate the mailbox geographically close to the user, in the same country or even in the same office building. However, while the protocol allows for such heterogeneous configurations, mail providers are discouraged from doing so, and are instead encouraged to provide one single configuration for all their users. For example, DNS resolution based on location, mail proxy servers, or other techniques as necessary, can be used to route the traffic and host the mail efficiently. This mechanism also allows the AutoConfig server to map the email address to a username that cannot be expressed using the Placeholders (see Section 3.6). However, this method is discouraged. Instead, the email server login should accept email addresses as username, and do the mapping to internal usernames at login time, which avoids the need for the client to know a different username. Bucksch Expires 6 May 2027 [Page 23] Internet-Draft autoconfig November 2026 AutoConfig servers that customize the returned configuration file to the email address should prevent email addresses from being tested for validity by hostile parties like spammers or attackers. Returning an error or a fake configuration for non-existing email addresses would allow the attacker to differentiate valid email addresses. A mitigation is to answer requests for non-existing email addresses with a random configuration from the set of valid configurations. A static configuration that works for all users is the preferred deployment method. 4.2. Central database The ISPDB (Internet service provider database) is a central database that contains the configurations for large mail providers. This is a useful fallback that allows mail clients to support mail providers which do not host a configuration server described in the previous step. This step is often necessary to find a working configuration for many email accounts. The mail client application chooses the mail configuration database provider. A public mail configuration 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 (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. Bucksch Expires 6 May 2027 [Page 24] Internet-Draft autoconfig November 2026 If the previous mechanisms yield no result, the client performs a DNS MX lookup on the email domain, and retrieves the MX server (incoming SMTP server) for that domain. Only the highest priority MX hostname is considered. From that MX hostname, two 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 Suffix List (https://publicsuffix.org) 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 configuration for these MX domains, using the previous methods, starting with: * 3.1. https://autoconfig.%MXFULLDOMAIN%/.well-known/client- autoconfig.xml?emailaddress=%EMAILADDRESS% (Required) * 3.2. https://autoconfig.%MXBASEDOMAIN%/.well-known/client- autoconfig.xml?emailaddress=%EMAILADDRESS% (Recommended) * 3.3. https://autoconfig.%MXFULLDOMAIN%/mail/config- v1.1.xml?emailaddress=%EMAILADDRESS% (Deprecated, but deployed) * 3.4. https://autoconfig.%MXBASEDOMAIN%/mail/config- v1.1.xml?emailaddress=%EMAILADDRESS% (Deprecated, but deployed) * 3.5. %ISPDB%%MXFULLDOMAIN% (Recommended) * 3.6. %ISPDB%%MXBASEDOMAIN% (Recommended) The emailaddress URL parameter is Optional. For example: Bucksch Expires 6 May 2027 [Page 25] Internet-Draft autoconfig November 2026 * 3.1. https://autoconfig.premium.europe.example.com/.well-known/ client-autoconfig.xml?emailaddress=fred@example.com * 3.2. https://autoconfig.example.com/.well-known/client- autoconfig.xml?emailaddress=fred@example.com * 3.3. https://autoconfig.premium.europe.example.com/mail/config- v1.1.xml?emailaddress=fred@example.com * 3.4. https://autoconfig.example.com/mail/config- v1.1.xml?emailaddress=fred@example.com * 3.5. https://v1.ispdb.net/premium.europe.example.com * 3.6. https://v1.ispdb.net/example.com 4.4. Local disk For testing purposes, a mail client 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 the mail client 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/acmemailapp/isp/example.com.xml * 4.2. /opt/acmemailapp/isp/example.com.xml 4.5. Other mechanisms A mail client may want to implement other mechanisms to find a configuration, for example Exchange AutoDiscover, DNS-SRV [RFC6186], or heuristic guessing. If the mail client implements 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 Security Considerations. Bucksch Expires 6 May 2027 [Page 26] Internet-Draft autoconfig November 2026 4.6. Manual configuration If the above mechanisms fail to provide a working configuration, or if the user explicitly chooses so, the mail client should give the end user the ability to manually enter a configuration, and use that configuration to configure the account. 5. Configuration validation 5.1. User approval Independent of the mechanisms used to find the configuration, before using that configuration, the mail client SHOULD display that configuration to the end user and let him confirm it. This is an important security precaution (Section 7), a client not asking for user approval needs to consider all security properties. When displaying the configuration for approval: * At least the second-level domain name(s) of the hostnames involved MUST be shown clearly and with high prominence. * To avoid spoofing, the client MUST NOT cut off parts of long second-level domains. 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, the mail client 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, the mail client 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. Bucksch Expires 6 May 2027 [Page 27] Internet-Draft autoconfig November 2026 Showing the URL or hostname allows the end user to verify to be at the expected page while logging in, e.g. the login server of their company, instead of the email hoster's page. It is important that the user verifies to enter the password on the right domain. 5.4. OAuth2 client requirements The client can decide whether to * use the to fetch the OAuth2 server metadata using [RFC8414] (e.g. /.well-known/oauth-authorization-server, see spec for issuer with path) or OpenID Connect Discovery [OpenIDConnect] (e.g. /.well-known/openid-configuration) and get the authorization_endpoint and token_endpoint values and other parameters from that JSON document, and compare the issuer value as specified by [RFC8414], or * use the and from this AutoConfig document, or * combine both methods and verify that the URLs match. Not all OAuth2 servers publish the metadata according to [RFC8414] or OpenID Connect Discovery [OpenIDConnect]. Particular care must be taken when authURL and tokenURL are on different hostnames, because it means that a user might be logging in at the correct login page, the app gets the auth code from the real auth server, and then sends the working auth code to the tokenURL server run by an attacker. The client application must handle this case with particular caution, e.g. by warning the user or aborting. Currently, one large mail provider uses such a split configuration, which could be worked around by hardcoding a whitelist or other methods. Either way, the client MUST check whether both the authURL and the tokenURL match either the email address domain or the server domain, and if not, MUST show that OAuth2 domain to the end user while the end user approves the servers (Section 5.1), or alternatively abort the process. 6. Configuration publishing by mail providers Mail service providers who want to support this specification and publish the mail configuration for their own mail service, so that mail client apps can be automatically configured, MUST follow this section as guideline and MUST respect the definitions in this specification. Bucksch Expires 6 May 2027 [Page 28] Internet-Draft autoconfig November 2026 * Configuration fields MUST NOT contain invalid or non-working configuration data. * The provided configuration MUST be working, and SHOULD use state- of-the-art security. * Configurations MUST be public and MUST NOT require authentication (see below). 6.1. Configuration location for a single domain The configuration file should be published at the URL for step 1.1., i.e. * https://autoconfig.%EMAILDOMAIN%/.well-known/client-autoconfig.xml e.g. for fred@example.com * https://autoconfig.example.com/.well-known/client-autoconfig.xml 6.2. Configuration location for domain hosters For mail providers which host entire domains for their business customers, the same URL 1.1., as listed in the previous section, is recommended. If that URL is not used, the configuration file should be published at the locations for step 3.1. and 3.2., i.e. * https://autoconfig.%MXFULLDOMAIN%/.well-known/client- autoconfig.xml * https://autoconfig.%MXBASEDOMAIN%/.well-known/client- autoconfig.xml For example, if the MX server for customer domain example.net is mx.premium.europe.example.com, then the configuration file should be at both * https://autoconfig.premium.europe.example.com/.well-known/client- autoconfig.xml * https://autoconfig.example.com/.well-known/client-autoconfig.xml If the MX server hostname is directly in the email domain, e.g. mail.example.com, then URL 3.1 would of course be the same URL as 3.2. Bucksch Expires 6 May 2027 [Page 29] Internet-Draft autoconfig November 2026 6.3. No authentication for configuration Any of the above URLs for retrieving the configuration file MUST NOT require authentication, but MUST be public. This is because the configuration information in the AutoConfig file includes the authentication method. Without the AutoConfig file, the client does not know which authentication method is required and which username form to use (e.g. username fred or fred@example.com or fred\EXAMPLE). Given that this information is required for authentication, the AutoConfig file itself cannot require authentication. 6.4. OAuth2 server requirements If OAuth2 is used, the OAuth2 server MUST adhere to the [OAuth2Client] specification, including all SHOULD requirements. However, given that * authURL * tokenURL * client ID * scope are provided in the AutoConfig response, the steps "Fetching the Authorization Server Metadata" and "Dynamic Client Registration" as well as scope names MAY be skipped in favor of the values in the AutoConfig response. What stays in force from [OAuth2Client] are the remaining guarantees in the [OAuth2Client] specification that the OAuth2 server gives to the mail client, including refresh token validity times. The provider MUST allow any client application that acts on behalf of the end user who the mailbox is for. Failure to do so implies a cartel or monopolistic behavior to lock out competing email applications from fulfilling their purpose on behalf of end users, which may be contrary to laws in multiple countries. The OAuth2 server MUST * accept the client ID that is given in the configuration file, or if that is not given, Bucksch Expires 6 May 2027 [Page 30] Internet-Draft autoconfig November 2026 * implement Dynamic Client Registration [RFC7591] or [CMID] in the way as defined by [OAuth2Client] and accept the resulting Client ID, without client secret. It MAY support multiple of those methods. The server MUST NOT employ any methods at any point to block or hinder client applications that are acting on behalf of end users. The specifications above contain requirements for expiry times and the login page, which are needed for mail client applications to work, and MUST be followed. The OAuth2 scope MUST include all services defined in this configuration file, so that a single user login is sufficient for all services. The resulting refresh and access tokens MUST be valid for all services defined in the configuration file, including for all URL-based protocols like CalDAV and all TCP-based protocols like IMAP. 7. Security Considerations 7.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 administrative 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. 7.2. DNS Any protocol that relies on DNS without further validation, e.g. HTTP or DNS SRV, should be considered insecure. This also applies to the MX lookup and the HTTPS calls that are based on its results. Bucksch Expires 6 May 2027 [Page 31] Internet-Draft autoconfig November 2026 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 configuration, particularly the resulting second-level domains. See User approval. 7.3. HTTP HTTP requests may be intercepted, redirected, or altered at the network level. See Risk above. Even if an http: URL redirects to an https: URL, that is still insecure. For that reason, clients MUST prefer HTTPS (URLs 1.1. to 1.3.) over HTTP (URL 1.4.) during configuration retrieval, within the same retrieval method. If such configs from HTTP are used, the end user MUST explicitly confirm the configuration, particularly the resulting second-level domains. See User approval. As mentioned above (Section 7.2), DNS SRV suffers from similar weaknesses. 7.4. Configuration 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 configuration 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. Bucksch Expires 6 May 2027 [Page 32] Internet-Draft autoconfig November 2026 7.5. Server security Given that mail clients will trust the configuration, the server delivering the configuration file needs to be secure. A static web server offers better security. The server software should be updated regularly and hosted on a dedicated secure server with all unnecessary services and server features turned off. 7.6. ISPDB For the Central database, 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 authoritative 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. The risk is mitigated to some degree by User approval. 7.7. User testing with emailaddress If the provider returns different configurations based on the emailaddress parameter of the URL, then attackers can find out whether a given email address is valid. See Section 4.1.2 for mitigations. It is recommended to return the same configuration for all users, which avoids this problem. 7.8. Rate-limits If rate-limits are used, the limits should be high enough for at least 100 requests per minute from the same client, given that normal clients routinely make 10 or more requests at once, and might repeat that process multiple times after user mistakes or configuration errors. A static configuration file served by a static web server is recommended. 8. IANA Considerations 8.1. Registration IANA will create the following registry in a new registry group called "Mail AutoConfig": Registry Name: "AutoConfig Protocol Type Names" Bucksch Expires 6 May 2027 [Page 33] Internet-Draft autoconfig November 2026 Registration Procedure: Specification Required, per [RFC8126], Section 4.6 Designated Expert: The author of this document. 8.2. Contents Table, with fields Element (alphanumeric), Type (alphanumeric), Base (URL or TCP or URL/TCP), Name, Specification, and Additional Elements The registrations need to define: * Element: The XML element wrapping the server section. * Type: The type attribute value of the server section. * Base: Whether the protocol is URL-based or TCP-based, * Name: The commonly used name of the protocol * Specification: Which RFCs or document specifies the protocol, and * Additional Elements: (Optional) Protocol-specific XML elements and their meaning. 8.3. Initial registration +==============+===========+====+===========+=========================+==========+ |Element |Type |Base|Name |Specification |Additional| | | | | | |Elements | +==============+===========+====+===========+=========================+==========+ |incomingServer|jmap |URL |JMAP |RFC 8620, RFC 8621, RFC | | | | | | |8887, RFC 9610 et al | | +--------------+-----------+----+-----------+-------------------------+----------+ |incomingServer|imap |TCP |IMAP |RFC 9051 or RFC 3501, et | | | | | | |al | | +--------------+-----------+----+-----------+-------------------------+----------+ |incomingServer|pop3 |TCP |POP3 |RFC 1939, RFC 5034 | | +--------------+-----------+----+-----------+-------------------------+----------+ |outgoingServer|smtp |TCP |SMTP |RFC 5321, RFC 5322 | | +--------------+-----------+----+-----------+-------------------------+----------+ |calendar |caldav |URL |CalDAV |RFC 4791 | | +--------------+-----------+----+-----------+-------------------------+----------+ |addressbook |carddav |URL |CardDAV |RFC 6352 | | +--------------+-----------+----+-----------+-------------------------+----------+ |fileShare |webdav |URL |WebDAV |RFC 4918 | | +--------------+-----------+----+-----------+-------------------------+----------+ |chatServer |xmpp |URL |XMPP |RFC 6120, RFC 6121, RFC | | Bucksch Expires 6 May 2027 [Page 34] Internet-Draft autoconfig November 2026 | | | | |7395 | | +--------------+-----------+----+-----------+-------------------------+----------+ |chatServer |xmpp-tcp |TCP |XMPP |RFC 6120, RFC 6121 | | +--------------+-----------+----+-----------+-------------------------+----------+ |chatServer |matrix |URL |Matrix |https://spec.matrix.org | | | | | | |(https://spec.matrix.org)| | +--------------+-----------+----+-----------+-------------------------+----------+ |setupServer |managesieve|TCP |ManageSieve|RFC 5804, RFC 5228 | | +--------------+-----------+----+-----------+-------------------------+----------+ |incomingServer|ews |URL |Exchange | | | | | | |Web | | | | | | |Services | | | +--------------+-----------+----+-----------+-------------------------+----------+ |incomingServer|activesync |URL |ActiveSync | | | +--------------+-----------+----+-----------+-------------------------+----------+ |incomingServer|graph |URL |Microsoft | | | | | | |Graph | | | +--------------+-----------+----+-----------+-------------------------+----------+ Table 3 The Additional Elements field is empty in all of the initial values. 9. References 9.1. Normative References [CalDAV] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, March 2007, . [CardDAV] Daboo, C., "CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)", RFC 6352, DOI 10.17487/RFC6352, August 2011, . [CMID] Parecki, A. and E. Smith, "OAuth Client ID Metadata Document", 2026, . [CRAM-MD5] Klensin, J., Catoe, R., and P. Krumviede, "IMAP/POP AUTHorize Extension for Simple Challenge/Response", RFC 2195, DOI 10.17487/RFC2195, September 1997, . Bucksch Expires 6 May 2027 [Page 35] Internet-Draft autoconfig November 2026 [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest Authentication as a SASL Mechanism", RFC 2831, DOI 10.17487/RFC2831, May 2000, . [EMail] Resnick, P., Ed., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008, . [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . [HTTP-Basic-Auth] Reschke, J., "The 'Basic' HTTP Authentication Scheme", RFC 7617, DOI 10.17487/RFC7617, September 2015, . [HTTP-Digest-Auth] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP Digest Access Authentication", RFC 7616, DOI 10.17487/RFC7616, September 2015, . [IMAP4rev1] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, . [IMAP4rev2] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message Access Protocol (IMAP) - Version 4rev2", RFC 9051, DOI 10.17487/RFC9051, August 2021, . [JMAP-Contacts] Jenkins, N., Ed., "JSON Meta Application Protocol (JMAP) for Contacts", RFC 9610, DOI 10.17487/RFC9610, December 2024, . [JMAP-Core] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, . Bucksch Expires 6 May 2027 [Page 36] Internet-Draft autoconfig November 2026 [JMAP-Mail] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, August 2019, . [JMAP-WebSocket] Murchison, K., "A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket", RFC 8887, DOI 10.17487/RFC8887, August 2020, . [ManageSieve] Melnikov, A., Ed. and T. Martin, "A Protocol for Remotely Managing Sieve Scripts", RFC 5804, DOI 10.17487/RFC5804, July 2010, . [Matrix] "Matrix protocol specification", n.d., . [OAuth2] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, . [OAuth2Client] Jenkins, N. and B. Bucksch, "OAuth Profile for Open Public Clients", 2026, . [OpenIDConnect] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery", 15 December 2023, . [POP3] Myers, J. and M. Rose, "Post Office Protocol - Version 3", STD 53, RFC 1939, DOI 10.17487/RFC1939, May 1996, . [POP3-SASL] Siemborski, R. and A. Menon-Sen, "The Post Office Protocol (POP3) Simple Authentication and Security Layer (SASL) Authentication Mechanism", RFC 5034, DOI 10.17487/RFC5034, July 2007, . Bucksch Expires 6 May 2027 [Page 37] Internet-Draft autoconfig November 2026 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, . [SASL] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple Authentication and Security Layer (SASL)", RFC 4422, DOI 10.17487/RFC4422, June 2006, . [SASL-OAuth2] Mills, W., Showalter, T., and H. Tschofenig, "A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth", RFC 7628, DOI 10.17487/RFC7628, August 2015, . [SCRAM] Hansen, T., "SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple Authentication and Security Layer (SASL) Mechanisms", RFC 7677, DOI 10.17487/RFC7677, November 2015, . [Sieve] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email Filtering Language", RFC 5228, DOI 10.17487/RFC5228, January 2008, . [SMTP] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, DOI 10.17487/RFC5321, October 2008, . [STARTTLS] Newman, C., "Using TLS with IMAP, POP3 and ACAP", RFC 2595, DOI 10.17487/RFC2595, June 1999, . Bucksch Expires 6 May 2027 [Page 38] Internet-Draft autoconfig November 2026 [TLSv1.2] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, . [URL] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [WebDAV] Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, June 2007, . [WebSocket] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, DOI 10.17487/RFC6455, December 2011, . [XMPP] Saint-Andre, P., "Extensible Messaging and Presence Protocol (XMPP): Core", RFC 6120, DOI 10.17487/RFC6120, March 2011, . [XMPP-IM] Saint-Andre, P., "Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence", RFC 6121, DOI 10.17487/RFC6121, March 2011, . [XMPP-WebSocket] Stout, L., Ed., Moffitt, J., and E. Cestari, "An Extensible Messaging and Presence Protocol (XMPP) Subprotocol for WebSocket", RFC 7395, DOI 10.17487/RFC7395, October 2014, . 9.2. Informative References [AutoConfig1.1] Bucksch, B., "AutoConfig version 1.1", 2020, . [DNS-SRV] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, DOI 10.17487/RFC2782, February 2000, . Bucksch Expires 6 May 2027 [Page 39] Internet-Draft autoconfig November 2026 [DNSSEC] Hoffman, P., "DNS Security Extensions (DNSSEC)", BCP 237, RFC 9364, DOI 10.17487/RFC9364, February 2023, . [GSSAPI] Linn, J., "Generic Security Service Application Program Interface Version 2, Update 1", RFC 2743, DOI 10.17487/RFC2743, January 2000, . [Kerberos] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The Kerberos Network Authentication Service (V5)", RFC 4120, DOI 10.17487/RFC4120, July 2005, . [RELAXNG] Clark, J., "RELAX NG Compact Syntax", 2002, . [RFC6186] Daboo, C., "Use of SRV Records for Locating Email Submission/Access Services", RFC 6186, DOI 10.17487/RFC6186, March 2011, . [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, . [XML] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols", BCP 70, RFC 3470, DOI 10.17487/RFC3470, January 2003, . Appendix A. Alternatives considered A.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. Bucksch Expires 6 May 2027 [Page 40] Internet-Draft autoconfig November 2026 Therefore, DNSSEC cannot be relied on in this specification, and DNS must be considered insecure for the purposes of this specification. A.2. DNS SRV DNS SRV protocols [DNS-SRV] [RFC6186] are not used here, for two reasons: 1. DNS SRV relies on insecure DNS and the configuration 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. OAuth2 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. A.3. CAPABILITIES Deployments in the wild from actual ISPs show that protocol-specific commands to find available authentication methods, e.g. IMAP CAPABILITY or POP3 CAPA, are not reliable. Many email servers advertise 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 of 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 Bucksch Expires 6 May 2027 [Page 41] Internet-Draft autoconfig November 2026 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 advertise [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 capabilities commands that include authentication methods. Appendix B. Implementations B.1. Clients Currently, this protocol or parts of it have been implemented by: * Thunderbird (https://thunderbird.net) * Parula (https://parula.beonex.com) * Evolution (https://projects.gnome.org/evolution/) * KMail (https://userbase.kde.org/KMail) * Kontact (https://www.kontact.org) * K-9 Mail (https://k9mail.app) and Thunderbird Mobile (https://www.thunderbird.net/mobile/) * FairEmail (https://email.faircode.eu) * Nextcloud Mail (https://apps.nextcloud.com/apps/mail) * Delta Chat (https://delta.chat/) and likely other mail clients. Bucksch Expires 6 May 2027 [Page 42] Internet-Draft autoconfig November 2026 B.2. Servers At the time of this writing, this specification is the most widely supported protocol for email client configuration. A large number of email domains use AutoConfig to provide the configuration to mail clients and allow an automatic setup. Some mail servers automatically provide AutoConfig files that follow this specification, including Stalwart (https://stalw.art/), Mailcow (https://mailcow.email/) and many others. Appendix C. RELAX NG schema This appendix specifies the RELAX NG compact syntax [RELAXNG] for the configuration file format defined in this document. It is provided for the convenience of implementers and not normative. Where the schema and the body of this document disagree, the body of this document is normative. The schema deliberately implements the must-ignore rule of XML validation: it accepts unknown attributes, unknown child elements, and unknown attribute and element values, instead of rejecting them. This is achieved by: * using text for the content of every value-bearing element, so that values that are not defined here still validate, for example a future socketType or authentication method. The values defined by this document are listed in comments next to the corresponding patterns * allowing any attribute whose name is not defined for a given element, using the attribute * - (...) and attribute * { text } patterns * allowing any element whose name is not defined by this schema, at every extension point, using the extensionElement pattern. Known elements are still validated against their own definitions. A malformed known element (for example, a whose content is not an integer) makes that element invalid, and therefore its enclosing server section is invalid as well. The remaining server sections and the rest of the document are still processed. A document is rejected as a whole only when it is not well-formed XML. The fragments shown in the body of this document are excerpts of the grammar below. The grammar below additionally carries the wildcards that implement the must-ignore rule. Bucksch Expires 6 May 2027 [Page 43] Internet-Draft autoconfig November 2026 # RELAX NG compact syntax schema for the Mail AutoConfig configuration file. # # This schema implements the must-ignore rule of Section "XML validation": # unknown attributes, unknown child elements and unknown values are accepted # rather than being rejected, so that clients can ignore them. default namespace = "" datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes" start = clientConfig # --- Wildcards used to implement the must-ignore rule ----------------------- # Any attribute (used on elements that define no attributes of their own). anyAttr = attribute * { text } # Any element at all, with any attributes and any content. Used inside # foreign (extension) subtrees, where everything is unknown and ignored. anyElement = element * { ( anyAttr | text | anyElement )* } # Any element whose name is NOT defined by this schema. Placed at every # extension point so that unknown elements validate, while known elements # are still matched (and validated) by their own patterns. extensionElement = element * - ( clientConfig | emailProvider | domain | displayName | displayShortName | documentation | descr | incomingServer | outgoingServer | calendar | addressbook | fileShare | chatServer | videoConference | setupServer | url | hostname | port | socketType | authentication | username | oAuth2 | authURL | tokenURL | issuer | scope | clientID | clientSecret | clientConfigUpdate ) { ( anyAttr | text | anyElement )* } # --- Global structure ------------------------------------------------------- clientConfig = element clientConfig { attribute version { text }, # e.g. "1.1" or "1.2" ( attribute * - version { text } )*, ( emailProvider | calendar | addressbook | fileShare | chatServer | videoConference | setupServer | oAuth2 | clientConfigUpdate | extensionElement )* } emailProvider = element emailProvider { attribute id { text }, Bucksch Expires 6 May 2027 [Page 44] Internet-Draft autoconfig November 2026 ( attribute * - id { text } )*, ( domain | displayName | displayShortName | documentation | incomingServer | outgoingServer | extensionElement )* } domain = element domain { attribute purpose { text }?, # the only defined value is "mx" ( attribute * - purpose { text } )*, text } displayName = element displayName { anyAttr*, text } displayShortName = element displayShortName { anyAttr*, text } documentation = element documentation { attribute url { text }, ( attribute * - url { text } )*, ( descr | extensionElement )* } descr = element descr { attribute lang { text }?, # 2-letter ISO language code ( attribute * - lang { text } )*, text } # --- Server sections -------------------------------------------------------- # # incomingServer, outgoingServer, calendar, addressbook, fileShare, # chatServer, videoConference and setupServer all share the same body. # Every child element is optional and may appear in any order; a section # that lacks the information needed for its protocol is simply ignored by # the client (Section "XML validation"). serverSection = attribute type { text }, # see the IANA registry ( attribute * - type { text } )*, ( url | hostname | port | socketType | authentication | username | extensionElement )* incomingServer = element incomingServer { serverSection } outgoingServer = element outgoingServer { serverSection } calendar = element calendar { serverSection } addressbook = element addressbook { serverSection } fileShare = element fileShare { serverSection } Bucksch Expires 6 May 2027 [Page 45] Internet-Draft autoconfig November 2026 chatServer = element chatServer { serverSection } videoConference = element videoConference { serverSection } setupServer = element setupServer { serverSection } # --- Server child elements -------------------------------------------------- url = element url { anyAttr*, text } hostname = element hostname { anyAttr*, text } port = element port { anyAttr*, xsd:positiveInteger } # 1-65535 socketType = element socketType { anyAttr*, text } # "SSL" / "STARTTLS" / "plain" username = element username { anyAttr*, text } authentication = element authentication { attribute system { text }?, # "http" or "sasl" ( attribute * - system { text } )*, text # e.g. "password-cleartext", "OAuth2" } # --- OAuth2 ----------------------------------------------------------------- oAuth2 = element oAuth2 { anyAttr*, ( authURL | tokenURL | issuer | scope | clientID | clientSecret | extensionElement )* } authURL = element authURL { anyAttr*, text } tokenURL = element tokenURL { anyAttr*, text } issuer = element issuer { anyAttr*, text } scope = element scope { anyAttr*, text } clientID = element clientID { anyAttr*, text } clientSecret = element clientSecret { anyAttr*, text } # --- Configuration update --------------------------------------------------- clientConfigUpdate = element clientConfigUpdate { attribute url { text }, ( attribute * - url { text } )*, ( extensionElement )* } Author's Address Ben Bucksch Beonex Bucksch Expires 6 May 2027 [Page 46] Internet-Draft autoconfig November 2026 Email: ben.bucksch@beonex.com Bucksch Expires 6 May 2027 [Page 47]