--- ``` __ __ ____ ___ ____ _/ /______/ /_ ____ _ / __ '__ \/ __ '/ __/ ___/ __ \/ __ '/ / / / / / / /_/ / /_/ /__/ / / / /_/ / /_/ /_/ /_/\__,_/\__/\___/_/ /_/\__,_/ ``` --- [![Go CI](https://github.com/floatpane/matcha/actions/workflows/ci.yml/badge.svg)](https://github.com/floatpane/matcha/actions/workflows/ci.yml) [![Go Release](https://github.com/floatpane/matcha/actions/workflows/release.yml/badge.svg)](https://github.com/floatpane/matcha/actions/workflows/release.yml) [![Go Version](https://img.shields.io/github/go-mod/go-version/floatpane/matcha)](https://golang.org) [![Go Report Card](https://goreportcard.com/badge/github.com/floatpane/matcha)](https://goreportcard.com/report/github.com/floatpane/matcha) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/floatpane/matcha)](https://github.com/floatpane/matcha/releases) [![GitHub All Releases](https://img.shields.io/github/downloads/floatpane/matcha/total)](https://github.com/floatpane/matcha/releases) [![GitHub license](https://img.shields.io/github/license/floatpane/matcha)](https://github.com/floatpane/matcha/blob/master/LICENSE) **A powerful, feature-rich email client for your terminal.** Built with Go and the Bubble Tea TUI framework, Matcha brings a beautiful, modern email experience to the command line with support for rich content, multiple accounts, and advanced terminal features.
![Demo GIF](public/assets/demo.gif) ## Installation View [INSTALLATION.md](docs/INSTALLATION.md) ## Features ### Email Management - **πŸ“¬ Inbox & Sent Mail**: View and manage emails from both inbox and sent folders - **πŸ“§ Multi-Account Support**: Manage multiple email accounts with an elegant tabbed interface - **⚑ Smart Caching**: Instant inbox display with background refresh for optimal performance - **πŸ”„ Real-time Refresh**: Manually refresh your inbox at any time with a single keypress - **♾️ Infinite Scroll**: Automatically loads more emails as you scroll through your inbox - **πŸ” Search & Filter**: Built-in filtering to quickly find emails by subject, sender, or content - **πŸ“– Rich Email Viewing**: - HTML email rendering with proper formatting - Markdown support for plain-text emails - Styled headers and body text - Proper handling of quoted-printable encoding - **πŸ’¬ Reply to Emails**: Quick reply with automatic quoting of original message - **πŸ—‘οΈ Delete & Archive**: Manage your inbox by deleting or archiving messages - **πŸ“Ž Attachment Support**: - Download email attachments to your Downloads folder - Automatic file opening after download - Smart filename handling (prevents overwrites with auto-numbering) - Support for various attachment encodings ### Rich Content Display Matcha supports modern terminal image protocols for displaying images directly in your terminal: #### **πŸ–ΌοΈ Image Protocol Support** - **Kitty Graphics Protocol**: Full support for Kitty, Ghostty, WezTerm, Wayst, and Konsole terminals - **iTerm2 Inline Images**: Native support for iTerm2 and Warp terminals - **Inline Email Images**: Display images embedded in HTML emails (including CID references) - **Remote Image Fetching**: Automatically fetches and displays remote images from URLs - **Data URI Support**: Renders base64-encoded inline images - **Smart Fallback**: Gracefully falls back to clickable links when images aren't supported #### **πŸ”— Terminal Hyperlinks (OSC 8)** - **Clickable Links**: Full OSC 8 hyperlink support for modern terminals - **Supported Terminals**: Kitty, Ghostty, WezTerm, Alacritty, iTerm2, Hyper, VS Code terminal, GNOME Terminal, and more - **Smart Detection**: Automatically detects terminal capabilities - **Fallback Mode**: Shows plain text URLs in unsupported terminals ### Composing Emails - **✍️ Compose New Emails**: Clean, intuitive interface for writing emails - **πŸ“ Markdown Support**: Write emails in Markdown that automatically converts to HTML - **πŸ–ΌοΈ Inline Images**: Embed images in your emails using Markdown syntax `![alt](path/to/image.png)` - **πŸ“Ž File Attachments**: Attach files with an integrated file picker - **πŸ‘₯ Contact Autocomplete**: Smart suggestions from your contact history - **πŸ’Ύ Auto-save Drafts**: Never lose your work - drafts are automatically saved - **πŸ“¨ Multi-Account Sending**: Choose which account to send from with a simple picker - **↩️ Reply Threading**: Proper email threading with In-Reply-To and References headers - **🎨 Rich Formatting**: Send both plain text and HTML versions of your emails ### Draft Management - **πŸ“ Automatic Draft Saving**: Drafts are saved when you exit the composer - **πŸ“‚ Draft Library**: View all your saved drafts in one place - **▢️ Resume Editing**: Pick up where you left off by reopening any draft - **πŸ—‘οΈ Draft Cleanup**: Delete drafts you no longer need - **⏰ Time Tracking**: See when each draft was last modified - **πŸ” Search Drafts**: Filter through your drafts by subject or recipient ### Account Management - **πŸ‘€ Multiple Accounts**: Configure and manage multiple email accounts - **πŸ”„ Easy Switching**: Switch between accounts with keyboard shortcuts or tabs - **βœ‰οΈ Provider Presets**: Built-in support for: - **Gmail** (imap.gmail.com / smtp.gmail.com) - **iCloud** (imap.mail.me.com / smtp.mail.me.com) - **Custom IMAP/SMTP**: Configure any email provider with custom server settings - **βš™οΈ Account Settings**: - Add new accounts - Remove existing accounts - Edit account details - Configure separate fetch and send addresses - **πŸ” Secure Storage**: Credentials stored locally in `~/.config/matcha/config.json` ### Contact Management - **πŸ“‡ Automatic Contact Saving**: Email addresses are automatically saved from: - Emails you receive - Emails you send - **πŸ” Smart Search**: Fuzzy search through your contacts while composing - **⚑ Quick Autocomplete**: Contact suggestions appear as you type in the "To" field - **πŸ’Ύ Persistent Storage**: Contacts are saved locally for offline access ### User Interface - **🎨 Beautiful TUI**: Clean, modern terminal interface built with Bubble Tea - **⌨️ Vim-like Keybindings**: Efficient keyboard navigation (`j/k`, `h/l`, etc.) - **πŸ“± Responsive Design**: Adapts to your terminal window size - **🎯 Focus Management**: Clear visual indication of focused elements - **πŸ“‘ Tabbed Interface**: Switch between accounts with tab navigation - **🎭 Styled Elements**: Color-coded interface elements for better readability - **πŸ’¬ Contextual Help**: Built-in help text shows available commands for each screen ### Advanced Features - **πŸ”„ Automatic Updates**: Built-in update checker notifies you of new releases - **⬆️ Self-Update Command**: Update Matcha with a simple `matcha update` command - **🎯 Smart Image Rendering**: Automatically calculates terminal cell size for proper image display - **πŸ› Debug Mode**: Environment variables for debugging image protocol issues - **πŸ”§ Flexible Configuration**: JSON-based configuration with automatic migration from legacy formats - **πŸš€ Performance Optimized**: Concurrent email fetching for faster inbox loading - **πŸ’Ύ Email Caching**: Instant inbox display on startup with background refresh ## Supported Email Providers Matcha works with any email provider that supports IMAP and SMTP. Here are the built-in presets: | Provider | IMAP Server | SMTP Server | Notes | |----------|-------------|-------------|-------| | **Gmail** | imap.gmail.com:993 | smtp.gmail.com:587 | Requires app-specific password | | **iCloud** | imap.mail.me.com:993 | smtp.mail.me.com:587 | Requires app-specific password | | **Custom** | Your server | Your server | Configure any IMAP/SMTP provider | ### Using Gmail or iCloud For Gmail and iCloud, you'll need to generate an **app-specific password**: - **Gmail**: [Create an App Password](https://support.google.com/accounts/answer/185833) - **iCloud**: [Generate an app-specific password](https://support.apple.com/en-us/HT204397) ## Usage ### First Launch On first launch, Matcha will prompt you to configure an email account. You'll need: - Your email address - Your password (or app-specific password for Gmail/iCloud) - Email provider (Gmail, iCloud, or Custom) ### Keyboard Shortcuts #### Main Menu - `↑/↓` or `j/k` - Navigate menu items - `Enter` - Select option - `Esc` - Go back / Exit - `Ctrl+C` - Quit application #### Inbox View - `↑/↓` or `j/k` - Navigate emails - `←/β†’` or `h/l` - Switch between account tabs - `Enter` - Open selected email - `/` - Filter/search emails - `r` - Refresh inbox - `d` - Delete selected email - `a` - Archive selected email - `Esc` - Back to main menu #### Email View - `↑/↓` or `j/k` - Scroll email content - `r` - Reply to email - `d` - Delete email - `a` - Archive email - `Tab` - Focus attachments - `Esc` - Back to inbox #### Attachment View (when focused) - `↑/↓` or `j/k` - Navigate attachments - `Enter` - Download and open attachment - `Tab` or `Esc` - Back to email body #### Composer - `Tab` / `Shift+Tab` - Navigate fields - `Enter` - - On "From" field: Select account (if multiple) - On "Attachment" field: Open file picker - On "Send" button: Send email - `↑/↓` - Navigate contact suggestions (when typing in "To" field) - `Esc` - Save draft and exit #### Settings - `↑/↓` or `j/k` - Navigate accounts - `Enter` - Add new account - `d` - Delete selected account - `Esc` - Back to main menu ### Updating Matcha Check for updates and install the latest version: ```bash matcha update ``` This command will: 1. Check for the latest release on GitHub 2. Detect your installation method (Homebrew, Snap, or binary) 3. Update using the appropriate method ## Terminal Compatibility ### Image Protocol Support For the best experience with inline images, use a terminal that supports modern image protocols: **Kitty Graphics Protocol:** - [Kitty](https://sw.kovidgoyal.net/kitty/) - [Ghostty](https://ghostty.org/) - [WezTerm](https://wezfurlong.org/wezterm/) - [Wayst](https://github.com/91861/wayst) - [Konsole](https://konsole.kde.org/) **iTerm2 Inline Images:** - [iTerm2](https://iterm2.com/) - [Warp](https://www.warp.dev/) ### Hyperlink Support (OSC 8) Clickable links work in: - Kitty, Ghostty, WezTerm, Alacritty, Foot - iTerm2, Hyper, Warp - VS Code integrated terminal - GNOME Terminal, Tilix (VTE-based terminals) - tmux, screen (when properly configured) ## Configuration > [!WARNING] > The passwords are stored in plain text as of right now, make sure your computer is not infected before using Matcha Configuration is stored in `~/.config/matcha/config.json` **Example configuration:** ```json { "accounts": [ { "id": "unique-id-1", "name": "John Doe", "email": "john@gmail.com", "password": "app-specific-password", "service_provider": "gmail", "fetch_email": "john@gmail.com" }, { "id": "unique-id-2", "name": "Work Email", "email": "john@company.com", "password": "password", "service_provider": "custom", "fetch_email": "john@company.com", "imap_server": "imap.company.com", "imap_port": 993, "smtp_server": "smtp.company.com", "smtp_port": 587 } ] } ``` ### Additional Data Locations - **Drafts**: `~/.config/matcha/drafts/` - **Email Cache**: `~/.config/matcha/cache.json` - **Contacts**: `~/.config/matcha/contacts.json` ## Debugging ### Image Protocol Debugging If images aren't displaying correctly, enable debug logging: ```bash export DEBUG_IMAGE_PROTOCOL=1 export DEBUG_IMAGE_PROTOCOL_LOG=/tmp/matcha-images.log matcha ``` Check the log file for detailed information about image rendering. ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## License This project is distributed under the MIT License. See the `LICENSE` file for more information. ## Credits Built with: - [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework - [Lipgloss](https://github.com/charmbracelet/lipgloss) - Style definitions - [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components - [go-imap](https://github.com/emersion/go-imap) - IMAP client - [go-message](https://github.com/emersion/go-message) - Email parsing - [Goldmark](https://github.com/yuin/goldmark) - Markdown rendering - [goquery](https://github.com/PuerkitoBio/goquery) - HTML parsing ---
**[Report Bug](https://github.com/floatpane/matcha/issues/new?template=bug_report.md)** Β· **[Request Feature](https://github.com/floatpane/matcha/issues/new?template=feature_request.md)** Β· **[Contributing Guidelines](https://github.com/floatpane/matcha/blob/master/CONTRIBUTING.md)**