How mjl-/mox works
Main Components
a. Protocol Servers:
• SMTP Server – (found under “smtp”, “smtpserver”, “smtpclient”) handles receiving, submitting, and delivering email.
• IMAP Server – (directories “imapserver”, “imapclient”) provides access to mailboxes via IMAP.
b. Web Interfaces & APIs:
• Webmail – (in “webmail”) is the browser-based email client.
• Admin & Webadmin – (directories “admin”, “webadmin”) supply an administrative interface for configuring domains, accounts, and managing settings.
• Web API & Webhooks – (found in “webapi”, “webapisrv”) offer HTTP/JSON endpoints for transactional email and delivery events.
c. Mail Authentication & Security:
• DKIM, DMARC, SPF – (directories “dkim”, “dmarc”, “spf”) implement signing/verification and reputation/tracking logic.
• DNS/DANE – (directories “dns”, “dane”, “dnsbl”) support DNS lookups, DANE and blocklist mechanisms.
d. TLS and Automatic Certificate Management:
• Autotls – (directory “autotls”) handles automatic TLS certificate generation (ACME integration).
e. Data Storage & Processing:
• Message Storage, Indexing, and Queuing – (directories “store”, “queue”, “message”) indicate how mail messages are stored on disk and indexed (using bbolt via the “bstore” library).
• Metrics & Logging – (files like “metrics.go”, “mlog”) provide operational insights.
f. Auxiliary and Integrations:
• Tools for backup, API documentation generation, and testing (e.g. “apidiff”, “gendoc.sh”, “testdata”) indicate operational support.
• Docker and deployment scripts (Dockerfiles, docker-compose files) denote deployment architecture.
• External integrations for ACME, Prometheus, etc., are also key players.
Relationships and Interactions
• External Clients (Mail user agents, web browsers, mobile apps) interact via different protocols:
– SMTP clients send outgoing mail to the SMTP server.
– IMAP clients retrieve emails from the IMAP server.
– Web users connect to the webmail or admin interfaces (served by the embedded webserver).
– External applications use REST/JSON APIs via the web API endpoints.
• The protocol servers (SMTP/IMAP) communicate with the core mail processing modules:
– Incoming email messages are processed (authenticated, possibly spam/virus checked, and passed on to the mail storage engine) and metadata is saved in the indexing databases.
• The authentication/security libraries (DKIM, DMARC, SPF) work as intermediaries during mail processing, verifying and tagging email authenticity.
• The automatic TLS component communicates with external Certificate Authorities (e.g. Let’s Encrypt) through ACME protocols.
• The configuration (from “config”) and backup data (from “store”, “queue”) are centrally managed and used by almost every module.
• The webserver (serving admin interfaces and webmail) shares the same TLS certificates and configuration as the rest of the system.
• Monitoring and metrics are exported (using Prometheus and structured logging) from the core components.
Architectural Patterns and Design Principles
• Modular design: Each protocol or service is implemented in its own package and directory, promoting separation of concerns.
• Layered architecture:
– Presentation Layer: Webmail, admin UI, API endpoints.
– Service/Protocol Layer: SMTP and IMAP servers.
– Core Processing Layer: Message handling, spam filtering, reputation tracking, authentication (DKIM/DMARC/SPF) and TLS/ACME.
– Data Storage Layer: File-based mail storage, bbolt databases via “bstore”, queues, and logs.
• Loose coupling via configuration files and externalized components (such as transports) that allow mox to work in a self‐contained style while still being customizable.
Elements
– SMTP Server (with subcomponents for submission, rate limiting, reputation filtering)
– IMAP Server and client interaction modules
– Webmail Interface & Admin Dashboard
– HTTP/JSON API (webapisrv)
– Mail Processing & Message Queue (queue, message) and Data Storage (store)
– Security/Validation modules (dkim, dmarc, spf)
– TLS/ACME and Automatic Certificate Management (autotls)
– DNS/DANE modules (dns, dane, dnsbl)
– Monitoring & Metrics (Prometheus integration)
• Notations for external interactions: Internet (for inbound/outbound mail), CA (for TLS), external email providers, and so on.
Final Advice for the Principal Software Engineer
• While the project structure is large, do not shy away from decomposing it into as many components as possible – this will help reveal dependencies and data flows very accurately.