🦉 Noctua Mail

A fast web-based mail client (IMAP/SMTP) built with Bun, TypeScript, and Next.js.

I am trying to combine the advantages of GMail, Thunderbird and Spark, step by step, keeping full IMAP compatibility using IMAP (custom) properties and relying on standard email headers for all features.

A working WebCal integration is planned, I need it, and it will be the first thing I will be working on after the mail client is stable and usable for daily use.

✨ Key Features

🧠 Adaptive Email Categorization

Automatic message categorization into Newsletter, Notification, and Transactional using a hybrid approach:

• Heuristic classifier based on robust mail headers and content signals
• Per-account online learning from manual category actions (set/change/clear)
• Manual override controls directly in the message action menu
• Debug visibility for learned model state and feedback events in Account Settings → Categorization

See doc/CATEGORIZATION.md for technical details.

🏷️ Topics

Local topic tagging for threads with lightweight learning from your past assignments:

• Manual topic assignment from the message menu for projects, interests, or workflows
• Learned suggestions based on sender, recipient, and mailing-list signals from previously tagged threads

🔗 Related Mails

Discover connections across your inbox with related mails. When viewing any email, instantly find related messages based on:

• Subject similarity – Find conversations on similar topics
• Sender/Recipient overlap – Track communications with the same people
• Thread references – Follow email chains using In-Reply-To and References headers
• Calendar invite UID matches – Find invitation updates/cancellations tied to the same event

Access via the "Show related" option in the message action menu or search with related:<mail-id>. For calendar invites, use invite:<uid> (or event:<uid>) to find related invitation mails.

🤖 MCP Integration

Built-in Model Context Protocol (MCP) support lets AI clients work with your mailbox through a structured, documented tool interface:

• Search and retrieval tools – Query messages, folders, topics, and mailing list aliases
• AI-friendly schemas – Discover tool inputs and outputs through MCP tools/list
• Actionable workflows – Create drafts and use mailbox data from external AI assistants without scraping the UI

🧵 Thread View Across Folders

Unified conversation threading that works across all folders. Whether emails are in Inbox, Sent, or any other folder, Noctua Mail intelligently groups them into cohesive threads. Collapse and expand conversations with ease, maintaining context no matter where messages are stored.

🎯 Workflow Views

Built-in virtual folders keep triage fast and actionable:

• Focused – Prioritized inbox view for what matters now
• Action Queue – Messages that are flagged, marked TODO, or marked done
• Invite Deck – Calendar invitation-focused view with unread/total counters

⏰ Calendar Invite Reminders

Schedule reminders directly from ICS invites and get desktop/system notifications at the right time:

• Per-invite reminder controls – Schedule, modify, and delete reminders from the invite preview
• Recurring invite support – Reminder timing follows recurring event rules (RRULE + exceptions)
• Automatic invite update handling – Reminder records are updated/removed when invite updates or cancellations arrive
• Offline-aware delivery – PWA/service worker delivery with local cache and due-lookback handling

✍️ Markdown Composing

Write emails in Markdown with a dedicated compose mode and send them as fully rendered HTML (with plain-text fallback), while preserving clean markdown source in drafts.

🔐 IMAP-Only Authentication

Simple, secure authentication using your existing IMAP credentials. No separate user accounts and no stored passwords to manage – just connect with your email server credentials and start using Noctua Mail immediately.

---

🚀 Features

📧 Email Management

• IMAP sync – Full folder and message synchronization
• SMTP support – Send and reply to emails
• Multiple accounts – Manage several email accounts
• Rich message viewing – HTML, Text, Markdown, and Source views
• Attachments – Inline display and downloadable files
• Calendar invites – Display ICS details (full calendar support in progress 📅)
• Calendar reminders – Schedule notifications for invite events, including recurring meetings
• Automatic invite updates – Apply invite changes/cancellations to existing reminder data

🎨 UI

• Three-pane layout – Folders, message list, and message view
• Dark mode 🌙 – Easy on the eyes
• Installable PWA 📱 – Install as a native app on desktop
• OS notifications 🔔 – Get notified of new emails
• Responsive design – Resizable panes with independent scrolling
• Per-message text scaling – Adjust font size (or zoom for HTML) for individual messages
• Virtualized lists ⚡ – Blazing-fast display of thousands of emails
• Workflow folders – Focused, Action Queue, and Invite Deck virtual views

🔍 Powerful Search

• Full-text search powered by SQLite FTS5
• Field filtering – Search by from: (even from:me), to:, subject:, and more
• Related mail search – Find connected conversations with related:<mail-id>
• Invitation mail search – Find invite-related mails via invite:<uid> (or event:<uid>)
• Search across all folders – Or narrow down to specific folders

💬 Smart Threading

• Intelligent conversation grouping – Automatically thread related messages
• Cross-folder threading – See complete conversations regardless of folder location
• Collapse/expand threads – Focus on what matters
• Visual thread indicators – Clear hierarchy and relationships

---

🛠️ Tech Stack

• Runtime – Bun
• Framework – Next.js (App Router)
• Language – TypeScript
• UI – Radix UI + Lucide Icons
• Email – ImapFlow + Nodemailer
• Database – SQLite (bun:sqlite) with FTS5 full-text search
• Rich Text – Lexical

---

🏃 Getting Started

Prerequisites

• Bun runtime installed

Installation

bun install
bun run dev

Open http://localhost:3654 in your browser.

Desktop app

Noctua Mail can also be packaged as a native desktop app using Tauri. See doc/DESKTOP.md for setup, development, and packaging instructions.

Testing

Run all tests:

bun test

Run only the message list behavior regression tests:

bun test app/components/mailclient/messagelist/listBehavior.test.ts

---

⚙️ Configuration

Data Storage

Local data is stored in .data/ directory:

• SQLite database
• Message sources
• Attachments (stored separately for performance)

Environment Variables

IMAP Credentials Storage

Configure how IMAP/SMTP credentials are stored:

IMAP_CREDENTIALS_STORAGE=both  # Options: cookie | db | both (default: both)

• cookie – Credentials only in sealed session cookie
• db – Credentials only in encrypted database
• both – Credentials in both cookie and encrypted database (recommended)

IMAP_SECRET_KEY=<32-byte-hex-key>  # Required for DB encryption

Authentication

Control access to the application:

SESSION_SEAL_KEY=<32-byte-hex-key>  # Required for session cookie sealing

Reverse Proxy / Rate Limiting

The rate limiter (applied to /api/auth/login, /api/auth/signup, /api/probe) keys requests by client IP. Since Request doesn't expose the TCP peer, it relies on X-Forwarded-For, which means the reverse proxy in front of Noctua must sanitise that header so a client can't spoof their own rate-limit identity.

Noctua assumes one trusted reverse proxy in front by default (no env var needed). The recommended Caddy configuration uses the global trusted_proxies directive, which instructs Caddy to ignore any X-Forwarded-For the client tries to send and insert the real remote IP instead:

{
    servers {
        trusted_proxies static private_ranges
    }
}

yourdomain.tld {
    reverse_proxy localhost:3654
}

If you need a different topology, use TRUSTED_PROXY_HOPS to override the default. The value is the number of reverse-proxy hops whose X-Forwarded-For entry Noctua should trust:

TRUSTED_PROXY_HOPS=1   # Default — single reverse proxy in front (no need to set this)
TRUSTED_PROXY_HOPS=2   # Two chained trusted proxies (e.g. Cloudflare → Caddy → Noctua)
TRUSTED_PROXY_HOPS=0   # Noctua directly on a public interface; ignore XFF entirely

• 1 (default) — rightmost X-Forwarded-For entry (the IP the proxy saw) is used.
• N ≥ 2 — the entry at XFF[length - N] is used. Requires at least N entries in XFF; if fewer are present (topology mismatch), the request falls back to the "unknown" global bucket rather than trusting a potentially client-supplied leftmost entry.
• 0 / false — forwarded headers are ignored; rate limiting becomes a single global bucket per limiter. Coarse, but safe when Noctua is exposed directly.

Data Directory

Customize the data directory location:

NOCTUA_DATA_DIR=../noctua-data  # Default: .data/

---

ℹ️ Current Limitations

• Desktop-optimized – Installable as a PWA, the UI is currently optimized and targeted for desktop use. Mails for mobile devices are better managed in a real app instead of a browser based webmail client. Mobile support will be improved over time, but it is not the primary focus.

---

📄 License

This project is licensed under the Elastic License 2.0.

You are free to:

• ✅ Use, modify, and distribute this software
• ✅ Host it yourself for personal or commercial use

You may not:

• ❌ Provide the software to third parties as a managed cloud service (SaaS)

---

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

The code is primarily written by AI agents (Claude, Codex, GitHub Copilot, Antigravity).

---

Built with ❤️ and 🤖 by Paul Wellner Bou