{"id":48811172,"url":"https://github.com/paulwellnerbou/noctua-mail","last_synced_at":"2026-04-14T07:30:29.257Z","repository":{"id":334902869,"uuid":"1143214749","full_name":"paulwellnerbou/noctua-mail","owner":"paulwellnerbou","description":"Web-based IMAP Mail Client","archived":false,"fork":false,"pushed_at":"2026-04-10T18:48:04.000Z","size":4918,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-10T20:20:24.290Z","etag":null,"topics":["imap-client","mail","webmail-client"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulwellnerbou.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-27T09:57:53.000Z","updated_at":"2026-04-10T18:48:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paulwellnerbou/noctua-mail","commit_stats":null,"previous_names":["paulwellnerbou/noctua-mail"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paulwellnerbou/noctua-mail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulwellnerbou%2Fnoctua-mail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulwellnerbou%2Fnoctua-mail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulwellnerbou%2Fnoctua-mail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulwellnerbou%2Fnoctua-mail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulwellnerbou","download_url":"https://codeload.github.com/paulwellnerbou/noctua-mail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulwellnerbou%2Fnoctua-mail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31786670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["imap-client","mail","webmail-client"],"created_at":"2026-04-14T07:30:26.667Z","updated_at":"2026-04-14T07:30:29.241Z","avatar_url":"https://github.com/paulwellnerbou.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# 🦉 Noctua Mail\n\n\u003cimg src=\"public/icons/icon-192.png\" alt=\"Noctua logo\" width=\"120\" style=\"float: right;\"/\u003e\n\nA fast web-based mail client (IMAP/SMTP) built with Bun, TypeScript, and Next.js.\n\nI 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.\n\nA 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.\n\n![noctua-mail.png](doc/noctua-mail.png)\n\n## ✨ Key Features\n\n### 🧠 Adaptive Email Categorization\nAutomatic message categorization into **Newsletter**, **Notification**, and **Transactional** using a hybrid approach:\n- **Heuristic classifier** based on robust mail headers and content signals\n- **Per-account online learning** from manual category actions (set/change/clear)\n- **Manual override controls** directly in the message action menu\n- **Debug visibility** for learned model state and feedback events in Account Settings → Categorization\n\nSee `doc/CATEGORIZATION.md` for technical details.\n\n### 🏷️ Topics\nLocal topic tagging for threads with lightweight learning from your past assignments:\n- **Manual topic assignment** from the message menu for projects, interests, or workflows\n- **Learned suggestions** based on sender, recipient, and mailing-list signals from previously tagged threads\n\n### 🔗 Related Mails\nDiscover connections across your inbox with related mails. When viewing any email, instantly find related messages based on:\n- **Subject similarity** – Find conversations on similar topics\n- **Sender/Recipient overlap** – Track communications with the same people\n- **Thread references** – Follow email chains using In-Reply-To and References headers\n- **Calendar invite UID matches** – Find invitation updates/cancellations tied to the same event\n\nAccess via the \"Show related\" option in the message action menu or search with `related:\u003cmail-id\u003e`. For calendar invites, use `invite:\u003cuid\u003e` (or `event:\u003cuid\u003e`) to find related invitation mails.\n\n### 🤖 MCP Integration\nBuilt-in **Model Context Protocol (MCP)** support lets AI clients work with your mailbox through a structured, documented tool interface:\n- **Search and retrieval tools** – Query messages, folders, topics, and mailing list aliases\n- **AI-friendly schemas** – Discover tool inputs and outputs through MCP `tools/list`\n- **Actionable workflows** – Create drafts and use mailbox data from external AI assistants without scraping the UI\n\n### 🧵 Thread View Across Folders\nUnified 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.\n\n### 🎯 Workflow Views\nBuilt-in virtual folders keep triage fast and actionable:\n- **Focused** – Prioritized inbox view for what matters now\n- **Action Queue** – Messages that are flagged, marked TODO, or marked done\n- **Invite Deck** – Calendar invitation-focused view with unread/total counters\n\n### ⏰ Calendar Invite Reminders\nSchedule reminders directly from ICS invites and get desktop/system notifications at the right time:\n- **Per-invite reminder controls** – Schedule, modify, and delete reminders from the invite preview\n- **Recurring invite support** – Reminder timing follows recurring event rules (`RRULE` + exceptions)\n- **Automatic invite update handling** – Reminder records are updated/removed when invite updates or cancellations arrive\n- **Offline-aware delivery** – PWA/service worker delivery with local cache and due-lookback handling\n\n### ✍️ Markdown Composing\nWrite 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.\n\n### 🔐 IMAP-Only Authentication\nSimple, 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.\n\n---\n\n## 🚀 Features\n\n### 📧 Email Management\n- **IMAP sync** – Full folder and message synchronization\n- **SMTP support** – Send and reply to emails\n- **Multiple accounts** – Manage several email accounts\n- **Rich message viewing** – HTML, Text, Markdown, and Source views\n- **Attachments** – Inline display and downloadable files\n- **Calendar invites** – Display ICS details (full calendar support in progress 📅)\n- **Calendar reminders** – Schedule notifications for invite events, including recurring meetings\n- **Automatic invite updates** – Apply invite changes/cancellations to existing reminder data\n\n### 🎨 UI\n- **Three-pane layout** – Folders, message list, and message view\n- **Dark mode** 🌙 – Easy on the eyes\n- **Installable PWA** 📱 – Install as a native app on desktop\n- **OS notifications** 🔔 – Get notified of new emails\n- **Responsive design** – Resizable panes with independent scrolling\n- **Per-message text scaling** – Adjust font size (or zoom for HTML) for individual messages\n- **Virtualized lists** ⚡ – Blazing-fast display of thousands of emails\n- **Workflow folders** – Focused, Action Queue, and Invite Deck virtual views\n\n### 🔍 Powerful Search\n- **Full-text search** powered by SQLite FTS5\n- **Field filtering** – Search by `from:` (even `from:me`), `to:`, `subject:`, and more\n- **Related mail search** – Find connected conversations with `related:\u003cmail-id\u003e`\n- **Invitation mail search** – Find invite-related mails via `invite:\u003cuid\u003e` (or `event:\u003cuid\u003e`)\n- **Search across all folders** – Or narrow down to specific folders\n\n### 💬 Smart Threading\n- **Intelligent conversation grouping** – Automatically thread related messages\n- **Cross-folder threading** – See complete conversations regardless of folder location\n- **Collapse/expand threads** – Focus on what matters\n- **Visual thread indicators** – Clear hierarchy and relationships\n\n---\n\n## 🛠️ Tech Stack\n\n- **Runtime** – [Bun](https://bun.sh)\n- **Framework** – [Next.js](https://nextjs.org) (App Router)\n- **Language** – TypeScript\n- **UI** – [Radix UI](https://www.radix-ui.com/themes) + [Lucide Icons](https://lucide.dev)\n- **Email** – [ImapFlow](https://imapflow.com) + [Nodemailer](https://nodemailer.com)\n- **Database** – SQLite (bun:sqlite) with FTS5 full-text search\n- **Rich Text** – [Lexical](https://lexical.dev)\n\n---\n\n## 🏃 Getting Started\n\n### Prerequisites\n- [Bun](https://bun.sh) runtime installed\n\n### Installation\n\n```bash\nbun install\nbun run dev\n```\n\nOpen [http://localhost:3654](http://localhost:3654) in your browser.\n\n### Desktop app\n\nNoctua Mail can also be packaged as a native desktop app using Tauri. See [`doc/DESKTOP.md`](doc/DESKTOP.md) for setup, development, and packaging instructions.\n\n### Testing\n\nRun all tests:\n\n```bash\nbun test\n```\n\nRun only the message list behavior regression tests:\n\n```bash\nbun test app/components/mailclient/messagelist/listBehavior.test.ts\n```\n\n---\n\n## ⚙️ Configuration\n\n### Data Storage\nLocal data is stored in `.data/` directory:\n- SQLite database\n- Message sources\n- Attachments (stored separately for performance)\n\n### Environment Variables\n\n#### IMAP Credentials Storage\nConfigure how IMAP/SMTP credentials are stored:\n\n```bash\nIMAP_CREDENTIALS_STORAGE=both  # Options: cookie | db | both (default: both)\n```\n\n- **`cookie`** – Credentials only in sealed session cookie\n- **`db`** – Credentials only in encrypted database\n- **`both`** – Credentials in both cookie and encrypted database (recommended)\n\n```bash\nIMAP_SECRET_KEY=\u003c32-byte-hex-key\u003e  # Required for DB encryption\n```\n\n#### Authentication\nControl access to the application:\n\n```bash\nSESSION_SEAL_KEY=\u003c32-byte-hex-key\u003e  # Required for session cookie sealing\n```\n\n### Data Directory\nCustomize the data directory location:\n\n```bash\nNOCTUA_DATA_DIR=../noctua-data  # Default: .data/\n```\n\n---\n\n## ℹ️ Current Limitations\n\n- **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.\n\n---\n\n## 📄 License\n\nThis project is licensed under the [Elastic License 2.0](LICENSE).\n\n**You are free to:**\n- ✅ Use, modify, and distribute this software\n- ✅ Host it yourself for personal or commercial use\n\n**You may not:**\n- ❌ Provide the software to third parties as a managed cloud service (SaaS)\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Feel free to open issues or submit pull requests.\n\nThe code is primarily written by AI agents (Claude, Codex, GitHub Copilot, Antigravity).\n\n---\n\nBuilt with ❤️ and 🤖 by [Paul Wellner Bou](https://paul.wellnerbou.de)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulwellnerbou%2Fnoctua-mail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulwellnerbou%2Fnoctua-mail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulwellnerbou%2Fnoctua-mail/lists"}