Architecture at a glance

OxiMail is a single Rust binary. It speaks JMAP, SMTP, IMAP, CalDAV, CardDAV, ManageSieve, and WebSocket on its own, with no Postfix, no Dovecot, no nginx, no external fail2ban, and no separate antivirus daemon. Every traditional mail-server sidecar is collapsed into the binary as a Rust crate. This page is a map, not a manual. For per-crate depth, follow on to the Architecture Reference.

​

The single-binary model

When you run OxiMail you get one process that hosts:

• One axum HTTP server that serves the JMAP API, the admin API, push endpoints, and the ACME / TLS plumbing.
• One SMTP component with two distinct listeners: port 25 for inbound mail and port 587 for authenticated submission. They are separate code paths on purpose, because submission validates the sender against the authenticated user’s identities and inbound does not.
• One storage stack: a SQLite database per organization (a tenant in the storage model), a Tantivy full-text index, and a content-addressed filesystem blob store.

Everything below runs in that one binary. There are no microservices to orchestrate.

​

The crates, by layer

OxiMail is a Cargo workspace of 30 AGPL-3.0-or-later crates, plus two in-house path-dependency crates that live alongside it. Crates are grouped by the architectural layer they own, not alphabetically.

​

Binary entry and HTTP dispatch

​

Mail surface

​

Groupware

​

Storage and crypto

​

Transport and interop

​

Cross-cutting

​

In-house mail-protocol crates

Two crates sit beside the workspace as path dependencies. They replace the third-party mail libraries OxiMail used to depend on, so the whole mail pipeline is in-house:

​

Request paths

OxiMail exposes one storage model behind several front doors.

• JMAP over HTTPS. A client posts a batched request to /jmap. The server authenticates the bearer token, parses the request, validates the advertised capabilities, dispatches each method call against the method registry, and returns one batched response (RFC 8620).
• Legacy protocols translate to the same storage. IMAP, CalDAV, CardDAV, and ManageSieve are translation layers, not parallel implementations. An IMAP FETCH ends up calling the same internal handlers as the equivalent JMAP method, then re-encodes the result back to the legacy wire format. The legacy feature gate controls whether they are compiled in.
• SMTP inbound and submission. Inbound mail on port 25 runs DKIM/SPF/DMARC verification and the spam pipeline, then is delivered through the same ingestion path that writes both the raw and structured forms of a message. Authenticated submission on port 587 is a separate path that validates the sender.
• Push. Clients receive state changes over Server-Sent Events (EventSource) or WebSocket, so a client knows what changed without polling.

​

The storage model

A few invariants shape every read and write.

• One backend trait, pooled connections. Every store is built on Arc<dyn SqlBackend> with an r2d2 connection pool. There is no Mutex<Connection> anywhere. A store never embeds a connection; it borrows one from the pool for the duration of a request.
• Organization isolation in the storage layer. tenant_id is a mandatory parameter on every store method, and every query carries a WHERE tenant_id = ? clause. A bug in a handler cannot physically reach another organization’s rows. This is defense in depth, separate from access control.
• Raw and structured email, stored once. At ingestion a message is parsed a single time. The raw RFC 5322 bytes go to the blob store and the parsed structure goes to the database. Derived properties such as hasAttachment, preview, and threadId are computed at ingestion and stored, never re-derived on read.
• Content-hash blob dedup. A blob is addressed by the SHA-256 of its content, so two identical attachments share one blob. Two emails that happen to share a Message-ID are still always two separate objects pointing at the same blob; deduplication never happens at the message level.
• Transactional /set. All writes in a /set handler bind to the same BEGIN IMMEDIATE transaction, so creates, updates, destroys, and change records either all land or none do.

​

The EventBus

Domain crates do not import each other. The mail crate never reaches into the calendar crate, and so on. Instead they communicate through an EventBus: one crate emits a domain event after a successful write, and any interested crate subscribes to it. For example, when an inbound message carries a calendar invitation, the mail side emits an event; the calendar side, subscribed to that event, creates or updates the calendar object. This keeps the crates decoupled and makes cross-domain behavior explicit and testable.

​

Where to go next

• Architecture Reference for per-crate detail.
• Core concepts for the data model and terminology.