Introduction to Mailiner

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• crates/mailiner-composer/src/lib.rs
• crates/mailiner-imap-connector/src/lib.rs
• crates/mailiner-app/src/message_loader.rs
• crates/mailiner-app/src/formatter/mod.rs
• crates/mailiner-mime/src/writer/mod.rs

Mailiner is a browser-based IMAP client written in Rust that prioritizes privacy, efficiency, and flexibility. It executes as a WebAssembly (WASM) application using the Dioxus framework, enabling it to act like a desktop email client within a browser environment. Sources: README.md:3-8, AGENTS.md:7-9

The system bypasses the need for intermediate application servers by establishing direct, client-side encrypted communication with IMAP servers. Because browsers restrict direct TCP connections, Mailiner routes traffic through a WebSocket-to-TCP proxy, ensuring the proxy cannot inspect the encrypted email content. Sources: README.md:10-23

System Architecture

Mailiner consists of several specialized crates that handle UI rendering, protocol communication, and message processing. The core application logic resides in mailiner-app, while protocol specifics are delegated to connector crates.

Core Components

Component	Responsibility
mailiner-app	Dioxus/WASM UI, message loading orchestration, and security policy enforcement.
mailiner-imap-connector	IMAP protocol handling, connection management, and session state.
mailiner-composer	Email draft modeling, rich text editing, and MIME export orchestration.
mailiner-mime	MIME serialization, transfer encoding, and RFC 5322 header formatting.
mailiner-html	Shared HTML/CSS sanitization policies for the viewer and composer.

Sources: crates/mailiner-app/README.md:3, crates/mailiner-composer/src/lib.rs:5-17, crates/mailiner-imap-connector/src/lib.rs:77-90, crates/mailiner-mime/src/lib.rs:1-4, crates/mailiner-html/Cargo.toml:5-6

Connection Flow

To circumvent browser networking limitations, Mailiner uses the following flow to connect to an IMAP server:

The WebSocket-to-TCP proxy acts as a transparent relay. Encryption is established between the browser and the IMAP server, preventing the proxy from accessing sensitive data. Sources: README.md:12-23

Technical Implementation

Message Loading Pipeline

Mailiner implements a multi-stage pipeline to load and display messages. The process begins by fetching the BODYSTRUCTURE to understand the message hierarchy before selectively fetching content sections.

The load_message function orchestrates this flow, skipping large attachments based on a MAX_PREFETCH_OCTETS budget of 2 MiB to maintain performance. Sources: crates/mailiner-app/src/message_loader.rs:14-45

Security and Privacy

The application enforces a strict Content-Security-Policy (CSP) to prevent XSS and unauthorized data exfiltration. Sources: README.md:33-40

• LocalStorage: Account settings, including passwords and proxy tokens, are stored only in the browser's localStorage.
• HTML Sanitization: The MessageFormatter strips JavaScript and remote resources by default to protect user privacy.
• Resource Blocking: Remote images are blocked unless the user explicitly opts in, preventing senders from tracking the user via remote pixels.

Sources: README.md:29-32, crates/mailiner-app/src/formatter/mod.rs:36-47, crates/mailiner-app/src/formatter/html.rs:43-65

Email Composition and Export

The mailiner-composer crate manages the lifecycle of an email draft. It separates the draft model from the transport layer. Sources: crates/mailiner-composer/src/lib.rs:5-9

Preparation and MIME Serialization

Before sending, the prepare_submit function validates the draft and serializes it into RFC 5322 compliant bytes. Sources: crates/mailiner-composer/src/export.rs:46-88

1. Validation: Checks for required fields like recipients (To).
2. MIME Tree Construction: Builds a tree of MimePart objects, handling multipart/alternative for text/html, multipart/related for inline images, and multipart/mixed for attachments.
3. Encoding: Applies quoted-printable encoding for text and Base64 for binary data.
4. Header Generation: Formats headers like Date, Message-ID, and From using RFC 5322 rules.

Sources: crates/mailiner-composer/src/export.rs:163-228, crates/mailiner-mime/src/writer/mod.rs:54-78

IMAP Connector Logic

The ImapConnector manages authenticated sessions and provides an abstraction for folder and message operations. Sources: crates/mailiner-imap-connector/src/lib.rs:77-90

• Session Management: Transitions between Disconnected, Unauthenticated, Authenticating, and Authenticated states.
• Sorting: Supports server-side SORT if advertised by the IMAP server; otherwise, it falls back to client-side arrival order.
• Partial Fetching: Uses BODY.PEEK with offsets to stream large parts in chunks, minimizing peak memory usage in the WASM environment.

Sources: crates/mailiner-imap-connector/src/lib.rs:69-75, crates/mailiner-imap-connector/src/lib.rs:411-460, crates/mailiner-imap-connector/src/lib.rs:699-760

Conclusion

Mailiner provides a secure, decentralized webmail experience by moving the IMAP client logic entirely into the browser's WASM runtime. By combining a robust Rust backend for protocol handling and MIME processing with a Dioxus-based UI, it achieves desktop-grade email functionality while maintaining strict privacy controls and resource efficiency. Sources: README.md:3-8, AGENTS.md:11-15