1<div align="center">
  2
  3---
  4
  5<img src = "assets/logo.png" width=200 height=200>
  6
  7```
  8             __       __
  9    ____ ___  ____ _/ /______/ /_  ____ _
 10    / __ '__ \/ __ '/ __/ ___/ __ \/ __ '/
 11  / / / / / / /_/ / /_/ /__/ / / / /_/ /
 12/_/ /_/ /_/\__,_/\__/\___/_/ /_/\__,_/
 13```
 14
 15---
 16
 17[![Go CI](https://github.com/floatpane/matcha/actions/workflows/ci.yml/badge.svg)](https://github.com/floatpane/matcha/actions/workflows/ci.yml)
 18[![Go Release](https://github.com/floatpane/matcha/actions/workflows/release.yml/badge.svg)](https://github.com/floatpane/matcha/actions/workflows/release.yml)
 19[![Go Version](https://img.shields.io/github/go-mod/go-version/floatpane/matcha)](https://golang.org)
 20[![Go Report Card](https://goreportcard.com/badge/github.com/floatpane/matcha)](https://goreportcard.com/report/github.com/floatpane/matcha)
 21[![GitHub release (latest by date)](https://img.shields.io/github/v/release/floatpane/matcha)](https://github.com/floatpane/matcha/releases)
 22[![GitHub All Releases](https://img.shields.io/github/downloads/floatpane/matcha/total)](https://github.com/floatpane/matcha/releases)
 23[![GitHub license](https://img.shields.io/github/license/floatpane/matcha)](https://github.com/floatpane/matcha/blob/master/LICENSE)
 24
 25**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.
 26
 27
 28</div>
 29
 30![Demo GIF](public/assets/demo.gif)
 31
 32## Installation
 33
 34View [INSTALLATION.md](docs/INSTALLATION.md)
 35
 36## Features
 37
 38### Email Management
 39
 40- **📬 Inbox & Sent Mail**: View and manage emails from both inbox and sent folders
 41- **📧 Multi-Account Support**: Manage multiple email accounts with an elegant tabbed interface
 42- **⚡ Smart Caching**: Instant inbox display with background refresh for optimal performance
 43- **🔄 Real-time Refresh**: Manually refresh your inbox at any time with a single keypress
 44- **♾️ Infinite Scroll**: Automatically loads more emails as you scroll through your inbox
 45- **🔍 Search & Filter**: Built-in filtering to quickly find emails by subject, sender, or content
 46- **📖 Rich Email Viewing**:
 47  - HTML email rendering with proper formatting
 48  - Markdown support for plain-text emails
 49  - Styled headers and body text
 50  - Proper handling of quoted-printable encoding
 51- **💬 Reply to Emails**: Quick reply with automatic quoting of original message
 52- **🗑️ Delete & Archive**: Manage your inbox by deleting or archiving messages
 53- **📎 Attachment Support**:
 54  - Download email attachments to your Downloads folder
 55  - Automatic file opening after download
 56  - Smart filename handling (prevents overwrites with auto-numbering)
 57  - Support for various attachment encodings
 58
 59### Rich Content Display
 60
 61Matcha supports modern terminal image protocols for displaying images directly in your terminal:
 62
 63#### **🖼️ Image Protocol Support**
 64
 65- **Kitty Graphics Protocol**: Full support for Kitty, Ghostty, WezTerm, Wayst, and Konsole terminals
 66- **iTerm2 Inline Images**: Native support for iTerm2 and Warp terminals
 67- **Inline Email Images**: Display images embedded in HTML emails (including CID references)
 68- **Remote Image Fetching**: Automatically fetches and displays remote images from URLs
 69- **Data URI Support**: Renders base64-encoded inline images
 70- **Smart Fallback**: Gracefully falls back to clickable links when images aren't supported
 71
 72#### **🔗 Terminal Hyperlinks (OSC 8)**
 73
 74- **Clickable Links**: Full OSC 8 hyperlink support for modern terminals
 75- **Supported Terminals**: Kitty, Ghostty, WezTerm, Alacritty, iTerm2, Hyper, VS Code terminal, GNOME Terminal, and more
 76- **Smart Detection**: Automatically detects terminal capabilities
 77- **Fallback Mode**: Shows plain text URLs in unsupported terminals
 78
 79### Composing Emails
 80
 81- **✍️ Compose New Emails**: Clean, intuitive interface for writing emails
 82- **📝 Markdown Support**: Write emails in Markdown that automatically converts to HTML
 83- **🖼️ Inline Images**: Embed images in your emails using Markdown syntax `![alt](path/to/image.png)`
 84- **📎 File Attachments**: Attach files with an integrated file picker
 85- **👥 Contact Autocomplete**: Smart suggestions from your contact history
 86- **💾 Auto-save Drafts**: Never lose your work - drafts are automatically saved
 87- **📨 Multi-Account Sending**: Choose which account to send from with a simple picker
 88- **↩️ Reply Threading**: Proper email threading with In-Reply-To and References headers
 89- **🎨 Rich Formatting**: Send both plain text and HTML versions of your emails
 90
 91### Draft Management
 92
 93- **📝 Automatic Draft Saving**: Drafts are saved when you exit the composer
 94- **📂 Draft Library**: View all your saved drafts in one place
 95- **▶️ Resume Editing**: Pick up where you left off by reopening any draft
 96- **🗑️ Draft Cleanup**: Delete drafts you no longer need
 97- **⏰ Time Tracking**: See when each draft was last modified
 98- **🔍 Search Drafts**: Filter through your drafts by subject or recipient
 99
100### Account Management
101
102- **👤 Multiple Accounts**: Configure and manage multiple email accounts
103- **🔄 Easy Switching**: Switch between accounts with keyboard shortcuts or tabs
104- **✉️ Provider Presets**: Built-in support for:
105  - **Gmail** (imap.gmail.com / smtp.gmail.com)
106  - **iCloud** (imap.mail.me.com / smtp.mail.me.com)
107  - **Custom IMAP/SMTP**: Configure any email provider with custom server settings
108- **⚙️ Account Settings**:
109  - Add new accounts
110  - Remove existing accounts
111  - Edit account details
112  - Configure separate fetch and send addresses
113- **🔐 Secure Storage**: Credentials stored locally in `~/.config/matcha/config.json`
114
115### Contact Management
116
117- **📇 Automatic Contact Saving**: Email addresses are automatically saved from:
118  - Emails you receive
119  - Emails you send
120- **🔍 Smart Search**: Fuzzy search through your contacts while composing
121- **⚡ Quick Autocomplete**: Contact suggestions appear as you type in the "To" field
122- **💾 Persistent Storage**: Contacts are saved locally for offline access
123
124### User Interface
125
126- **🎨 Beautiful TUI**: Clean, modern terminal interface built with Bubble Tea
127- **⌨️ Vim-like Keybindings**: Efficient keyboard navigation (`j/k`, `h/l`, etc.)
128- **📱 Responsive Design**: Adapts to your terminal window size
129- **🎯 Focus Management**: Clear visual indication of focused elements
130- **📑 Tabbed Interface**: Switch between accounts with tab navigation
131- **🎭 Styled Elements**: Color-coded interface elements for better readability
132- **💬 Contextual Help**: Built-in help text shows available commands for each screen
133
134### Advanced Features
135
136- **🔄 Automatic Updates**: Built-in update checker notifies you of new releases
137- **⬆️ Self-Update Command**: Update Matcha with a simple `matcha update` command
138- **🎯 Smart Image Rendering**: Automatically calculates terminal cell size for proper image display
139- **🐛 Debug Mode**: Environment variables for debugging image protocol issues
140- **🔧 Flexible Configuration**: JSON-based configuration with automatic migration from legacy formats
141- **🚀 Performance Optimized**: Concurrent email fetching for faster inbox loading
142- **💾 Email Caching**: Instant inbox display on startup with background refresh
143
144## Supported Email Providers
145
146Matcha works with any email provider that supports IMAP and SMTP. Here are the built-in presets:
147
148| Provider | IMAP Server | SMTP Server | Notes |
149|----------|-------------|-------------|-------|
150| **Gmail** | imap.gmail.com:993 | smtp.gmail.com:587 | Requires app-specific password |
151| **iCloud** | imap.mail.me.com:993 | smtp.mail.me.com:587 | Requires app-specific password |
152| **Custom** | Your server | Your server | Configure any IMAP/SMTP provider |
153
154### Using Gmail or iCloud
155
156For Gmail and iCloud, you'll need to generate an **app-specific password**:
157
158- **Gmail**: [Create an App Password](https://support.google.com/accounts/answer/185833)
159- **iCloud**: [Generate an app-specific password](https://support.apple.com/en-us/HT204397)
160
161
162
163## Usage
164
165### First Launch
166
167On first launch, Matcha will prompt you to configure an email account. You'll need:
168
169- Your email address
170- Your password (or app-specific password for Gmail/iCloud)
171- Email provider (Gmail, iCloud, or Custom)
172
173### Keyboard Shortcuts
174
175#### Main Menu
176- `↑/↓` or `j/k` - Navigate menu items
177- `Enter` - Select option
178- `Esc` - Go back / Exit
179- `Ctrl+C` - Quit application
180
181#### Inbox View
182- `↑/↓` or `j/k` - Navigate emails
183- `←/→` or `h/l` - Switch between account tabs
184- `Enter` - Open selected email
185- `/` - Filter/search emails
186- `r` - Refresh inbox
187- `d` - Delete selected email
188- `a` - Archive selected email
189- `Esc` - Back to main menu
190
191#### Email View
192- `↑/↓` or `j/k` - Scroll email content
193- `r` - Reply to email
194- `d` - Delete email
195- `a` - Archive email
196- `Tab` - Focus attachments
197- `Esc` - Back to inbox
198
199#### Attachment View (when focused)
200- `↑/↓` or `j/k` - Navigate attachments
201- `Enter` - Download and open attachment
202- `Tab` or `Esc` - Back to email body
203
204#### Composer
205- `Tab` / `Shift+Tab` - Navigate fields
206- `Enter` -
207  - On "From" field: Select account (if multiple)
208  - On "Attachment" field: Open file picker
209  - On "Send" button: Send email
210- `↑/↓` - Navigate contact suggestions (when typing in "To" field)
211- `Esc` - Save draft and exit
212
213#### Settings
214- `↑/↓` or `j/k` - Navigate accounts
215- `Enter` - Add new account
216- `d` - Delete selected account
217- `Esc` - Back to main menu
218
219### Updating Matcha
220
221Check for updates and install the latest version:
222
223```bash
224matcha update
225```
226
227This command will:
2281. Check for the latest release on GitHub
2292. Detect your installation method (Homebrew, Snap, or binary)
2303. Update using the appropriate method
231
232## Terminal Compatibility
233
234### Image Protocol Support
235
236For the best experience with inline images, use a terminal that supports modern image protocols:
237
238**Kitty Graphics Protocol:**
239- [Kitty](https://sw.kovidgoyal.net/kitty/)
240- [Ghostty](https://ghostty.org/)
241- [WezTerm](https://wezfurlong.org/wezterm/)
242- [Wayst](https://github.com/91861/wayst)
243- [Konsole](https://konsole.kde.org/)
244
245**iTerm2 Inline Images:**
246- [iTerm2](https://iterm2.com/)
247- [Warp](https://www.warp.dev/)
248
249### Hyperlink Support (OSC 8)
250
251Clickable links work in:
252- Kitty, Ghostty, WezTerm, Alacritty, Foot
253- iTerm2, Hyper, Warp
254- VS Code integrated terminal
255- GNOME Terminal, Tilix (VTE-based terminals)
256- tmux, screen (when properly configured)
257
258## Configuration
259
260> [!WARNING]
261> The passwords are stored in plain text as of right now, make sure your computer is not infected before using Matcha
262
263Configuration is stored in `~/.config/matcha/config.json`
264
265**Example configuration:**
266
267```json
268{
269  "accounts": [
270    {
271      "id": "unique-id-1",
272      "name": "John Doe",
273      "email": "john@gmail.com",
274      "password": "app-specific-password",
275      "service_provider": "gmail",
276      "fetch_email": "john@gmail.com"
277    },
278    {
279      "id": "unique-id-2",
280      "name": "Work Email",
281      "email": "john@company.com",
282      "password": "password",
283      "service_provider": "custom",
284      "fetch_email": "john@company.com",
285      "imap_server": "imap.company.com",
286      "imap_port": 993,
287      "smtp_server": "smtp.company.com",
288      "smtp_port": 587
289    }
290  ]
291}
292```
293
294### Additional Data Locations
295
296- **Drafts**: `~/.config/matcha/drafts/`
297- **Email Cache**: `~/.config/matcha/cache.json`
298- **Contacts**: `~/.config/matcha/contacts.json`
299
300## Debugging
301
302### Image Protocol Debugging
303
304If images aren't displaying correctly, enable debug logging:
305
306```bash
307export DEBUG_IMAGE_PROTOCOL=1
308export DEBUG_IMAGE_PROTOCOL_LOG=/tmp/matcha-images.log
309matcha
310```
311
312Check the log file for detailed information about image rendering.
313
314## Contributing
315
316Contributions are welcome! Please feel free to submit a Pull Request.
317
318## License
319
320This project is distributed under the MIT License. See the `LICENSE` file for more information.
321
322## Credits
323
324Built with:
325- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework
326- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Style definitions
327- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components
328- [go-imap](https://github.com/emersion/go-imap) - IMAP client
329- [go-message](https://github.com/emersion/go-message) - Email parsing
330- [Goldmark](https://github.com/yuin/goldmark) - Markdown rendering
331- [goquery](https://github.com/PuerkitoBio/goquery) - HTML parsing
332
333---
334
335<div align="center">
336
337**[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)**
338
339</div>