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[](https://github.com/floatpane/matcha/actions/workflows/ci.yml)
18[](https://github.com/floatpane/matcha/actions/workflows/release.yml)
19[](https://goreleaser.com)
20[](https://golang.org)
21[](https://goreportcard.com/report/github.com/floatpane/matcha)
22
23[](https://github.com/floatpane/matcha/releases)
24[](https://github.com/floatpane/matcha/releases)
25[](https://github.com/floatpane/matcha/stargazers)
26[](https://github.com/floatpane/matcha/issues)
27[](https://github.com/floatpane/matcha/blob/master/LICENSE)
28
29[](https://www.apple.com/macos)
30[](https://www.linux.org/)
31[](https://brew.sh)
32[](https://snapcraft.io/matcha)
33
34[](https://patreon.com/andrinoff)
35[](https://github.com/floatpane/matcha/graphs/contributors)
36[](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
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 ``
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 matcha
180```
181
182After installation, run:
183
184```bash
185matcha
186```
187
188### Install using Snap
189
190```bash
191sudo snap install matcha
192```
193
194### Build from Source
195
196Matcha is written in **Go**. To build it manually:
197
1981. Ensure you have Go installed (`go version`).
1992. Clone the repository:
200
201 ```bash
202 git clone https://github.com/floatpane/matcha.git
203 ```
204
2053. Navigate to the project folder:
206
207 ```bash
208 cd matcha
209 ```
210
2114. Build the binary:
212
213 ```bash
214 go build -trimpath -ldflags="-s -w" -o matcha
215 ```
216
217 For an even smaller binary, compress with UPX (install via `brew install upx` or `apt install upx`):
218
219 ```bash
220 upx --best --lzma matcha
221 ```
222
223> [!WARNING]
224> UPX compression does NOT work on macOS ARM builds. See [#97](https://github.com/floatpane/matcha/pull/97)
225
2265. Run it:
227 ```bash
228 ./matcha
229 ```
230
231## Usage
232
233### First Launch
234
235On first launch, Matcha will prompt you to configure an email account. You'll need:
236
237- Your email address
238- Your password (or app-specific password for Gmail/iCloud)
239- Email provider (Gmail, iCloud, or Custom)
240
241### Keyboard Shortcuts
242
243#### Main Menu
244- `↑/↓` or `j/k` - Navigate menu items
245- `Enter` - Select option
246- `Esc` - Go back / Exit
247- `Ctrl+C` - Quit application
248
249#### Inbox View
250- `↑/↓` or `j/k` - Navigate emails
251- `←/→` or `h/l` - Switch between account tabs
252- `Enter` - Open selected email
253- `/` - Filter/search emails
254- `r` - Refresh inbox
255- `d` - Delete selected email
256- `a` - Archive selected email
257- `Esc` - Back to main menu
258
259#### Email View
260- `↑/↓` or `j/k` - Scroll email content
261- `r` - Reply to email
262- `d` - Delete email
263- `a` - Archive email
264- `Tab` - Focus attachments
265- `Esc` - Back to inbox
266
267#### Attachment View (when focused)
268- `↑/↓` or `j/k` - Navigate attachments
269- `Enter` - Download and open attachment
270- `Tab` or `Esc` - Back to email body
271
272#### Composer
273- `Tab` / `Shift+Tab` - Navigate fields
274- `Enter` -
275 - On "From" field: Select account (if multiple)
276 - On "Attachment" field: Open file picker
277 - On "Send" button: Send email
278- `↑/↓` - Navigate contact suggestions (when typing in "To" field)
279- `Esc` - Save draft and exit
280
281#### Settings
282- `↑/↓` or `j/k` - Navigate accounts
283- `Enter` - Add new account
284- `d` - Delete selected account
285- `Esc` - Back to main menu
286
287### Updating Matcha
288
289Check for updates and install the latest version:
290
291```bash
292matcha update
293```
294
295This command will:
2961. Check for the latest release on GitHub
2972. Detect your installation method (Homebrew, Snap, or binary)
2983. Update using the appropriate method
299
300## Terminal Compatibility
301
302### Image Protocol Support
303
304For the best experience with inline images, use a terminal that supports modern image protocols:
305
306**Kitty Graphics Protocol:**
307- [Kitty](https://sw.kovidgoyal.net/kitty/)
308- [Ghostty](https://ghostty.org/)
309- [WezTerm](https://wezfurlong.org/wezterm/)
310- [Wayst](https://github.com/91861/wayst)
311- [Konsole](https://konsole.kde.org/)
312
313**iTerm2 Inline Images:**
314- [iTerm2](https://iterm2.com/)
315- [Warp](https://www.warp.dev/)
316
317### Hyperlink Support (OSC 8)
318
319Clickable links work in:
320- Kitty, Ghostty, WezTerm, Alacritty, Foot
321- iTerm2, Hyper, Warp
322- VS Code integrated terminal
323- GNOME Terminal, Tilix (VTE-based terminals)
324- tmux, screen (when properly configured)
325
326## Configuration
327
328> [!WARNING]
329> The passwords are stored in plain text as of right now, make sure your computer is not infected before using Matcha
330
331Configuration is stored in `~/.config/matcha/config.json`
332
333**Example configuration:**
334
335```json
336{
337 "accounts": [
338 {
339 "id": "unique-id-1",
340 "name": "John Doe",
341 "email": "john@gmail.com",
342 "password": "app-specific-password",
343 "service_provider": "gmail",
344 "fetch_email": "john@gmail.com"
345 },
346 {
347 "id": "unique-id-2",
348 "name": "Work Email",
349 "email": "john@company.com",
350 "password": "password",
351 "service_provider": "custom",
352 "fetch_email": "john@company.com",
353 "imap_server": "imap.company.com",
354 "imap_port": 993,
355 "smtp_server": "smtp.company.com",
356 "smtp_port": 587
357 }
358 ]
359}
360```
361
362### Additional Data Locations
363
364- **Drafts**: `~/.config/matcha/drafts/`
365- **Email Cache**: `~/.config/matcha/cache.json`
366- **Contacts**: `~/.config/matcha/contacts.json`
367
368## Debugging
369
370### Image Protocol Debugging
371
372If images aren't displaying correctly, enable debug logging:
373
374```bash
375export DEBUG_IMAGE_PROTOCOL=1
376export DEBUG_IMAGE_PROTOCOL_LOG=/tmp/matcha-images.log
377matcha
378```
379
380Check the log file for detailed information about image rendering.
381
382## Contributing
383
384Contributions are welcome! Please feel free to submit a Pull Request.
385
386## License
387
388This project is distributed under the MIT License. See the `LICENSE` file for more information.
389
390## Credits
391
392Built with:
393- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework
394- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Style definitions
395- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components
396- [go-imap](https://github.com/emersion/go-imap) - IMAP client
397- [go-message](https://github.com/emersion/go-message) - Email parsing
398- [Goldmark](https://github.com/yuin/goldmark) - Markdown rendering
399- [goquery](https://github.com/PuerkitoBio/goquery) - HTML parsing
400
401---
402
403<div align="center">
404
405**[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)**
406
407Made with ♥ for terminal enthusiasts
408
409</div>