happyDomain/checker-email-autoconfig
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
4 commits 1 branch 2 tags 69 KiB
  • Go 98.2%
  • Makefile 1%
  • Dockerfile 0.8%
Find a file
Exact
Pierre-Olivier Mercier a716ff568f docker: add HEALTHCHECK probing /health 
The binary doubles as its own healthcheck client via the SDK's
-healthcheck flag, so the probe works in the scratch image
(no shell, no curl, no wget).
2026-04-26 11:01:36 +07:00
checker checker: report skipped rules as StatusUnknown 2026-04-26 09:50:13 +07:00
plugin checker: report skipped rules as StatusUnknown 2026-04-26 09:50:13 +07:00
.gitignore Initial commit 2026-04-26 09:50:13 +07:00
Dockerfile docker: add HEALTHCHECK probing /health 2026-04-26 11:01:36 +07:00
go.mod docker: add HEALTHCHECK probing /health 2026-04-26 11:01:36 +07:00
go.sum docker: add HEALTHCHECK probing /health 2026-04-26 11:01:36 +07:00
LICENSE Initial commit 2026-04-26 09:50:13 +07:00
main.go Initial commit 2026-04-26 09:50:13 +07:00
Makefile Initial commit 2026-04-26 09:50:13 +07:00
NOTICE Initial commit 2026-04-26 09:50:13 +07:00
README.md Initial commit 2026-04-26 09:50:13 +07:00

README.md

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 produced

Rule What it checks
autoconfig_presence At least one discovery method serves a valid clientConfig.
autoconfig_preferred_endpoint autoconfig.<domain> (Thunderbird's first try) is reachable.
autoconfig_tls HTTPS is mandatory and certificates validate.
autoconfig_server_encryption Advertised IMAP/SMTP servers use SSL/STARTTLS, not plaintext.
autoconfig_consistency clientConfig claims the queried domain and agrees with SRV.
autoconfig_srv_records RFC 6186 SRV records cover incoming + submission.
autoconfig_autodiscover Microsoft Autodiscover responds (informational).

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.