Autoconfig, Autodiscover, and the .mobileconfig: making Thunderbird, Outlook, and Apple Mail set themselves up
"Automatic mail-client setup" is not one feature. It's three incompatible discovery protocols wearing the same trenchcoat. Here are the exact DNS records, XML bodies, TLS caveats, and curl checks to serve all of them from one small set of endpoints.
EvilMail TeamJuly 29, 202612 min read
A user types their address and password into a fresh mail client. The client thinks for a second, finds nothing, and drops them onto a manual form: incoming server, port, SSL/STARTTLS, outgoing server, another port, another security dropdown, username-is-it-the-full-address-or-not. Six fields and three chances to guess wrong. A real fraction of those users close the app and open a support ticket instead — or abandon your service entirely.
The thing everyone calls "automatic setup" is not one feature. It is three mutually incompatible discovery protocols that happen to solve the same problem. Thunderbird speaks Mozilla autoconfig XML. Outlook speaks Microsoft's POX Autodiscover. Apple Mail speaks neither for plain IMAP — it guesses hostnames, validates TLS, and consumes signed .mobileconfig profiles. Serve only one and two-thirds of your users fall through to that manual form. Serve all three and it collapses to two fields — because every surface comes from one small set of DNS records, a couple of static XML files, one tiny dynamic handler, and a single TLS certificate. Here is exactly what each client probes, in what order, and the file you put at each URL.
The three discovery protocols, and why you need all three
Thunderbird → Mozilla autoconfig. Thunderbird looks for an XML document named config-v1.1.xml on a subdomain you control, then in a .well-known path, then in Mozilla's public database. It is a plain
Autoconfig & Autodiscover XML: Auto-Setup for Thunderbird, Outlook, Apple Mail — EvilMail Blog
GET
, the response is static, and it is the cleanest of the three.
Outlook → POX Autodiscover. Classic Outlook POSTs an XML request to a fixed path and expects a "Plain Old XML" response describing your IMAP and SMTP servers. The request carries the user's address; your response has to echo it back, so this one is not quite static.
Apple Mail → nothing, for plain IMAP. Apple Mail has no autoconfig endpoint for IMAP accounts. It guesses common hostnames, connects, and trusts whatever presents a valid certificate on the expected ports. For deterministic or fleet setup you hand it a signed .mobileconfig profile. (It *does* do Autodiscover — but only for Exchange/EWS, never plain IMAP.)
There is no shared standard here, and there is not going to be one. The closest thing to universal is RFC 6186, the SRV-record convention, which every one of these clients consults as a fallback. Ship that too — it is three DNS records and it catches the stragglers.
Almost everything below is static XML plus DNS. The single dynamic piece is a ~15-line handler that echoes the address back inside the Autodiscover response.
Thunderbird: Mozilla autoconfig
Thunderbird walks a fixed order. First it hits the ISP-hosted URL on your autoconfig. subdomain with the address as a query parameter. If that 404s or the certificate is wrong, it tries the .well-known path on the bare domain (TB 91+). Only then does it fall back to Mozilla's public ISPDB, then an MX-based ISPDB lookup, then blind hostname guessing.
You own the first two URLs. Serve identical content at both:
`socketType`.SSL means implicit TLS from the first byte — 993 for IMAP, 465 for SMTP. STARTTLS means plaintext-then-upgrade — 143 and 587. plain means no encryption; never ship it. Mismatch the value and the port (say, SSL on 587) and the client connects, hangs, and reports a vague timeout.
`authentication`.password-cleartext is the honest name for "send the password inside the TLS tunnel" — it is what you want for IMAP/SMTP AUTH. password-encrypted means CRAM-MD5 and requires server support. OAuth2 is for providers running a token flow.
`username`.%EMAILADDRESS% is the full address; %EMAILLOCALPART% is everything before the @; %EMAILDOMAIN% is the domain. If your Dovecot expects the full address as the login (most virtual-user setups do), use %EMAILADDRESS%.
The TLS caveat that eats hours: if the certificate on autoconfig.example.com does not cover that exact hostname, Thunderbird does not warn — it silently skips the ISP-hosted step, falls through to the ISPDB, finds nothing, and drops to manual entry. The autoconfig hostname must be in your certificate's SAN list.
Outlook: POX Autodiscover
Classic Outlook tries, in order: https://example.com/autodiscover/autodiscover.xml, then https://autodiscover.example.com/autodiscover/autodiscover.xml, then an http:// request to the same host expecting a 302 to HTTPS, then the _autodiscover._tcp SRV record, then its hardcoded Office 365 fallback. Note that step one hits your bare domain — usually your marketing site. Return valid Autodiscover XML there or issue a clean 302 to the autodiscover. host. A 200 with an HTML page confuses the parser.
LoginName must equal the address the client submitted. That single requirement is why a flat file does not cut it — you have to read the request body and template one field back. A minimal Next.js route handler at app/autodiscover/autodiscover.xml/route.ts:
ts
export async function POST(req: Request) {
const body = await req.text();
const email = body.match(/<EMailAddress>(.*?)<\/EMailAddress>/)?.[1] ?? "";
const xml = TEMPLATE.replaceAll("%EMAILADDRESS%", email);
return new Response(xml, { headers: { "content-type": "application/xml" } });
}
The 2024+ reality. "New Outlook" — the WebView2-based rewrite Microsoft is pushing on Windows 11 — deprioritized and in practice dropped POX IMAP Autodiscover for non-Microsoft accounts, steering users toward Microsoft/M365 accounts and OAuth. Classic Outlook (the Win32 client) still honors POX and will for years, so ship it — it is a near-static handler and it works. Just do not promise new Outlook one-click setup for plain IMAP. Those users go through Apple's path, SRV, or manual entry, and there is currently nothing you can serve to change that.
Apple Mail: guessing plus the profile
Apple Mail has no IMAP autoconfig endpoint. When someone adds an "other" mail account, it probes mail., imap., and smtp. under the domain and trusts whatever answers with a valid certificate on 993/587. So the cheapest possible win is to publish imap.example.com and smtp.example.com A records, terminate TLS with a certificate whose SAN covers both, and let Apple Mail find them. The same hostnames feed Thunderbird's final guessing step, so this one move helps two clients at once.
For deterministic setup — and mandatory for MDM/fleet deployment — ship a .mobileconfig, an XML plist with a com.apple.mail.managed payload:
Sign it with a certificate chaining to a CA the device trusts. An unsigned profile installs, but the OS labels it Unverified in red during install — a trust-killer you do not want in front of a new user. Host it at a stable URL like https://example.com/profile.mobileconfig, serve it as application/x-apple-aspen-config, and let users tap it once.
The DNS and endpoint map you actually provision
Four hostnames, one certificate, a handful of records and files.
Static autoconfig via nginx, if you are not routing it through the app:
nginx
location = /mail/config-v1.1.xml {
default_type application/xml;
alias /var/www/autoconfig/config-v1.1.xml;
}
Get one certificate covering all four SANs — with certbot that is -d autoconfig.example.com -d autodiscover.example.com -d imap.example.com -d smtp.example.com. Every discovery endpoint must be reachable without authentication and return application/xml. Several clients reject a text/html error page outright, so a misconfigured 404 that serves your styled error page breaks discovery even when the record exists.
Verify before you ship
Do not trust "it looked right in the editor." Probe every surface the way the clients do.
For Autodiscover specifically, run the Microsoft Remote Connectivity Analyzer at testconnectivity.microsoft.com — pick the Autodiscover (Outlook) test; it walks the exact probe order and tells you which step failed. Then do the only test that actually counts: a fresh Thunderbird profile plus "Add Account," an iOS "add mail account," and a classic Outlook run against a real mailbox.
Go-live checklist:
DNS present:autoconfig and autodiscover CNAMEs, imap/smtp A records, three SRV records resolving.
Certificate SANs cover all four hostnames — check with openssl, not the browser padlock.
Content-type is application/xml on every XML endpoint; no HTML error pages leaking through.
Root-domain Autodiscover probe returns valid XML or a clean 302 — not a 200 HTML marketing page.
`.mobileconfig` is signed by a trusted CA; no red "Unverified."
No auth on any discovery endpoint.
Autodiscover echoes the submitted address in LoginName.
Get this right and setup collapses to two fields — address and password, nothing else — on Thunderbird, Apple Mail, and classic Outlook alike. The honest frontier is new Outlook and OAuth: Microsoft's WebView2 client no longer plays nicely with POX for third-party IMAP, and token-based auth is where client autoconfig is drifting next. For everything shipping today, static XML and four DNS records still carry the load.
