Skip to content
MailDock Docs

Client autoconfiguration (autoconfig / autodiscover)

Purpose. A user types their address and password into Thunderbird, Apple Mail, K-9 or Outlook and the client finds the IMAP/SMTP settings itself — no support ticket, no “port 993 with SSL” instructions.

Behaviour.

  • With ACME TLS the DNS record list contains CNAME autoconfig.<domain> → <hostname> and CNAME autodiscover.<domain> → <hostname>; Caddy routes those hosts to the API and issues their certificates on demand (vetted by /api/v1/internal/tls-ask, known active domains only, like MTA-STS). A domain routed to another server gets neither row and neither certificate: its mailboxes live there.
  • https://autoconfig.<domain>/mail/config-v1.1.xml — Mozilla autoconfig (Thunderbird, K-9/Thunderbird Android, many others): IMAP 993 SSL / 143 STARTTLS, SMTP 587 STARTTLS / 465 SSL, username = full address.
  • https://autodiscover.<domain>/autodiscover/autodiscover.xml (POST) — Outlook / Windows Mail POX autodiscover with IMAP 993 + SMTP 587 and the requested address as login name; a request with no <EMailAddress> gets the literal placeholder %EMAILADDRESS% as its login name.
  • The existing _imaps._tcp / _submission._tcp SRV rows (RFC 6186) cover clients that use SRV lookup. Unlike the two CNAMEs, they are still listed for a domain routed to another server, pointing at this host; do not publish them for such a domain.
  • Unknown or inactive domains, and domains routed to another server, get 404; documents are generated from the current configuration’s hostname.
  • POP3 is never advertised, whether or not the server offers it (ServerConfig.protocols.pop3): both documents name IMAP and SMTP only, so a client set up from them keeps working when an administrator turns POP3 off.

Configuration. None; requires tls.mode = acme (per-domain certificates). Without it the rows are absent and the endpoints answer only when reached directly.

Limits & edge cases.

  • Apple Mail uses SRV + guessing, not autoconfig; it works because the SRV rows and the standard ports exist.
  • Outlook’s autodiscover probes https://<domain>/autodiscover/… first (the domain’s own web site); only the autodiscover.<domain> step reaches this server. Exchange/ActiveSync is not offered.
  • Autoconfig documents are public by design (they contain only hostnames and ports).