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