checker-email-autoconfig

Email autoconfiguration checker for happyDomain.

Verifies that a domain publishes discoverable email-client configuration through the mechanisms used by real-world mail clients:

• Thunderbird autoconfig (Bucksch draft, draft-bucksch-autoconfig-00)
  • https://autoconfig.<domain>/mail/config-v1.1.xml (primary)
  • https://<domain>/.well-known/autoconfig/mail/config-v1.1.xml (apex fallback)
  • http://autoconfig.<domain>/... (optional; surfaced as a warning)
  • Mozilla ISPDB fallback (autoconfig.thunderbird.net)
  • MX-parent fallbacks for hosted domains
• Microsoft Autodiscover POX (https://autodiscover.<domain>/autodiscover/autodiscover.xml)
• RFC 6186 SRV records (_imaps, _imap, _pop3s, _pop3, _submissions, _submission, _autodiscover)
• MX resolution (for context and MX-based discovery)

The checker parses every response, cross-checks the servers advertised by the different sources, and produces a rich HTML report with paste-ready remediation snippets for the most common failure modes.

Rules

Code	Description	Severity
autoconfig_presence	Checks that at least one email-autoconfiguration discovery method answers for the domain.	CRITICAL
autoconfig_preferred_endpoint	Checks that https://autoconfig.<domain>/mail/config-v1.1.xml is reachable and serves a valid clientConfig.	WARNING
autoconfig_tls	Checks that autoconfig endpoints are served over HTTPS with a valid TLS certificate.	CRITICAL
autoconfig_server_encryption	Checks that servers advertised by autoconfig use SSL or STARTTLS and a non-cleartext auth method.	CRITICAL
autoconfig_consistency	Cross-checks hostnames and ports reported by autoconfig, Autodiscover and SRV records.	WARNING
autoconfig_srv_records	Checks that RFC 6186 SRV records (_imaps._tcp, _submissions._tcp, ...) complement the autoconfig XML.	WARNING
autoconfig_autodiscover	Reports whether Microsoft Autodiscover (POX) responds on the domain.	WARNING

Common failure modes the HTML report addresses

When a check fails, the report's "Fix this first" section provides ready-to-copy snippets:

• Nothing is published → sample config-v1.1.xml for the domain and the two canonical URLs to serve it from.
• Only .well-known answers → nudge to add the autoconfig. subdomain (primary URL per the draft).
• Plain HTTP fallback responds → redirect to HTTPS.
• TLS validation failed → hint at covering autoconfig.<domain> with a valid certificate.
• Advertised servers are plaintext → port cheat-sheet (SSL 993/465, STARTTLS 143/587).
• No RFC 6186 SRV records → ready-to-paste zone excerpt.

Usage

Standalone

make
./checker-email-autoconfig -listen :8080

Exposes:

• GET /health, GET /definition
• POST /collect: run the full discovery probe.
• POST /evaluate: apply rules to a previously collected observation.
• POST /report: returns HTML when Accept: text/html is set, otherwise JSON metrics.

Docker

make docker
docker run -p 8080:8080 happydomain/checker-email-autoconfig

happyDomain plugin

make plugin
# produces checker-email-autoconfig.so, loadable by happyDomain.

Options

Per-user

• probeEmail: local-part used in the autoconfig URL query string (default test).
• httpTimeout: per-request timeout in seconds (default 8).
• tryISPDB: query Mozilla's Thunderbird ISPDB as a fallback (default true).
• tryHTTPAutoconfig: also probe the plain-HTTP variant (default false).
• tryAutodiscoverPost: probe the Microsoft Autodiscover POX endpoints (default true).

Admin

• ispdbURL: override the ISPDB base URL.
• userAgent: User-Agent announced in every probe.

License

MIT. See LICENSE and NOTICE.