PicoMail

A macOS email client built with Python and PySide6.

Status

This project was largely coded with Claude (Anthropic's AI), and the core functionality works: IMAP sync, Gmail OAuth, compose, reply, archive, search, etc.

Some highlights that turned out well:

• LanguageTool integration - spell/grammar checking with your own API key
• Cursor/external editor integration - draft editing syncs bidirectionally with your editor
• Vim keybindings - full vim-style navigation and compose editing
• Maildir storage - messages stored as plain files, fully hackable

The app works, but requires polish. Smoothing out these edges would more time than I'm willing to invest now.

If you enjoy hacking on desktop apps, this could be a good starting point for a lightweight, hackable macOS-native email client. The codebase is clean, fully typed Python, and the architecture (Qt + async backends + Maildir) is solid. Fork it and make it your own.

— Tom, January 2026

---

Features

• Inline spell and Grammer check with LanguageTool
• Markdown compose with live HTML preview
• Vim keybindings throughout (compose + navigation)
• External editor support with two-way sync
• Messages stored as files (Maildir format)
• IMAP + Gmail API support with setup wizard
• Unified inbox across accounts
• Conversation threading
• Full-text search (FTS5)
• Command palette (Cmd+K)
• Undo send (configurable delay)
• Draft auto-save on close
• Offline mode with sync-on-reconnect

Installation

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .

Or with uv:

uv pip install -e .

Usage

# Run the application
picomail

Development

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type check
mypy src/picomail

# Lint
ruff check src/picomail

Architecture

UI (PySide6)
├── MainWindow: 3-pane layout (folders, message list, message view)
├── ComposeWindow: Markdown editor with vim keybindings
└── Dialogs: Account wizard, settings, spell check

Core
├── SyncEngine: Orchestrates sync, manages backends
├── Models: Pydantic models (Message, Account, Folder, Thread)
└── Storage:
    ├── Database: SQLite with FTS5 for metadata and search
    └── Maildir: RFC 2822 message files

Backends
├── IMAPBackend: aioimaplib + SMTP
└── GmailBackend: Google API with OAuth2