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://golang.org)
20[](https://goreportcard.com/report/github.com/floatpane/matcha)
21[](https://github.com/floatpane/matcha/releases)
22[](https://github.com/floatpane/matcha/releases)
23[](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
31
32## Installation
33There are several ways to install Matcha:
34
35### Package Managers
36
37#### Homebrew (macOS & Linux)
38
39```bash
40brew tap floatpane/matcha
41brew install floatpane/matcha/matcha
42```
43
44After installation, run:
45
46```bash
47matcha
48```
49
50> [!WARNING]
51> If you have the [*"other"* Matcha](https://github.com/piqoni/matcha) already installed, you will have to rename the executable
52
53
54### Install using Snap (Linux)
55
56> [!NOTE]
57> When using Snap, the config folder is going to be located at `~/snap/matcha/36/.config`, see [why](https://github.com/floatpane/matcha/issues/117)
58
59```bash
60sudo snap install matcha
61```
62
63### Build from Source
64
65Matcha is written in **Go**. To build it manually:
66
671. Ensure you have Go installed (`go version`).
682. Clone the repository:
69
70 ```bash
71 git clone https://github.com/floatpane/matcha.git
72 ```
73
743. Navigate to the project folder:
75
76 ```bash
77 cd matcha
78 ```
79
804. Build the binary:
81
82 ```bash
83 go build -trimpath -ldflags="-s -w" -o matcha
84 ```
85
86 For an even smaller binary, compress with UPX (install via `brew install upx` or `apt install upx`):
87
88 ```bash
89 upx --best --lzma matcha
90 ```
91
92> [!WARNING]
93> UPX compression does NOT work on macOS ARM builds. See [#97](https://github.com/floatpane/matcha/pull/97)
94
955. Run it:
96 ```bash
97 ./matcha
98 ```
99
100### Open Build Service
101
102Also, a build of Matcha is available on [OBS](https://build.opensuse.org/package/show/home:mantarimay:apps/matcha). Thanks, [@mantarimay](https://github.com/mantarimay)!
103
104## Features
105
106### Email Management
107
108- **📬 Inbox & Sent Mail**: View and manage emails from both inbox and sent folders
109- **📧 Multi-Account Support**: Manage multiple email accounts with an elegant tabbed interface
110- **⚡ Smart Caching**: Instant inbox display with background refresh for optimal performance
111- **🔄 Real-time Refresh**: Manually refresh your inbox at any time with a single keypress
112- **♾️ Infinite Scroll**: Automatically loads more emails as you scroll through your inbox
113- **🔍 Search & Filter**: Built-in filtering to quickly find emails by subject, sender, or content
114- **📖 Rich Email Viewing**:
115 - HTML email rendering with proper formatting
116 - Markdown support for plain-text emails
117 - Styled headers and body text
118 - Proper handling of quoted-printable encoding
119- **💬 Reply to Emails**: Quick reply with automatic quoting of original message
120- **🗑️ Delete & Archive**: Manage your inbox by deleting or archiving messages
121- **📎 Attachment Support**:
122 - Download email attachments to your Downloads folder
123 - Automatic file opening after download
124 - Smart filename handling (prevents overwrites with auto-numbering)
125 - Support for various attachment encodings
126
127### Rich Content Display
128
129Matcha supports modern terminal image protocols for displaying images directly in your terminal:
130
131#### **🖼️ Image Protocol Support**
132
133- **Kitty Graphics Protocol**: Full support for Kitty, Ghostty, WezTerm, Wayst, and Konsole terminals
134- **iTerm2 Inline Images**: Native support for iTerm2 and Warp terminals
135- **Inline Email Images**: Display images embedded in HTML emails (including CID references)
136- **Remote Image Fetching**: Automatically fetches and displays remote images from URLs
137- **Data URI Support**: Renders base64-encoded inline images
138- **Smart Fallback**: Gracefully falls back to clickable links when images aren't supported
139
140#### **🔗 Terminal Hyperlinks (OSC 8)**
141
142- **Clickable Links**: Full OSC 8 hyperlink support for modern terminals
143- **Supported Terminals**: Kitty, Ghostty, WezTerm, Alacritty, iTerm2, Hyper, VS Code terminal, GNOME Terminal, and more
144- **Smart Detection**: Automatically detects terminal capabilities
145- **Fallback Mode**: Shows plain text URLs in unsupported terminals
146
147### Composing Emails
148
149- **✍️ Compose New Emails**: Clean, intuitive interface for writing emails
150- **📝 Markdown Support**: Write emails in Markdown that automatically converts to HTML
151- **🖼️ Inline Images**: Embed images in your emails using Markdown syntax ``
152- **📎 File Attachments**: Attach files with an integrated file picker
153- **👥 Contact Autocomplete**: Smart suggestions from your contact history
154- **💾 Auto-save Drafts**: Never lose your work - drafts are automatically saved
155- **📨 Multi-Account Sending**: Choose which account to send from with a simple picker
156- **↩️ Reply Threading**: Proper email threading with In-Reply-To and References headers
157- **🎨 Rich Formatting**: Send both plain text and HTML versions of your emails
158
159### Draft Management
160
161- **📝 Automatic Draft Saving**: Drafts are saved when you exit the composer
162- **📂 Draft Library**: View all your saved drafts in one place
163- **▶️ Resume Editing**: Pick up where you left off by reopening any draft
164- **🗑️ Draft Cleanup**: Delete drafts you no longer need
165- **⏰ Time Tracking**: See when each draft was last modified
166- **🔍 Search Drafts**: Filter through your drafts by subject or recipient
167
168### Account Management
169
170- **👤 Multiple Accounts**: Configure and manage multiple email accounts
171- **🔄 Easy Switching**: Switch between accounts with keyboard shortcuts or tabs
172- **✉️ Provider Presets**: Built-in support for:
173 - **Gmail** (imap.gmail.com / smtp.gmail.com)
174 - **iCloud** (imap.mail.me.com / smtp.mail.me.com)
175 - **Custom IMAP/SMTP**: Configure any email provider with custom server settings
176- **⚙️ Account Settings**:
177 - Add new accounts
178 - Remove existing accounts
179 - Edit account details
180 - Configure separate fetch and send addresses
181- **🔐 Secure Storage**: Credentials stored locally in `~/.config/matcha/config.json`
182
183### Contact Management
184
185- **📇 Automatic Contact Saving**: Email addresses are automatically saved from:
186 - Emails you receive
187 - Emails you send
188- **🔍 Smart Search**: Fuzzy search through your contacts while composing
189- **⚡ Quick Autocomplete**: Contact suggestions appear as you type in the "To" field
190- **💾 Persistent Storage**: Contacts are saved locally for offline access
191
192### User Interface
193
194- **🎨 Beautiful TUI**: Clean, modern terminal interface built with Bubble Tea
195- **⌨️ Vim-like Keybindings**: Efficient keyboard navigation (`j/k`, `h/l`, etc.)
196- **📱 Responsive Design**: Adapts to your terminal window size
197- **🎯 Focus Management**: Clear visual indication of focused elements
198- **📑 Tabbed Interface**: Switch between accounts with tab navigation
199- **🎭 Styled Elements**: Color-coded interface elements for better readability
200- **💬 Contextual Help**: Built-in help text shows available commands for each screen
201
202### Advanced Features
203
204- **🔄 Automatic Updates**: Built-in update checker notifies you of new releases
205- **⬆️ Self-Update Command**: Update Matcha with a simple `matcha update` command
206- **🎯 Smart Image Rendering**: Automatically calculates terminal cell size for proper image display
207- **🐛 Debug Mode**: Environment variables for debugging image protocol issues
208- **🔧 Flexible Configuration**: JSON-based configuration with automatic migration from legacy formats
209- **🚀 Performance Optimized**: Concurrent email fetching for faster inbox loading
210- **💾 Email Caching**: Instant inbox display on startup with background refresh
211
212## Supported Email Providers
213
214Matcha works with any email provider that supports IMAP and SMTP. Here are the built-in presets:
215
216| Provider | IMAP Server | SMTP Server | Notes |
217|----------|-------------|-------------|-------|
218| **Gmail** | imap.gmail.com:993 | smtp.gmail.com:587 | Requires app-specific password |
219| **iCloud** | imap.mail.me.com:993 | smtp.mail.me.com:587 | Requires app-specific password |
220| **Custom** | Your server | Your server | Configure any IMAP/SMTP provider |
221
222### Using Gmail or iCloud
223
224For Gmail and iCloud, you'll need to generate an **app-specific password**:
225
226- **Gmail**: [Create an App Password](https://support.google.com/accounts/answer/185833)
227- **iCloud**: [Generate an app-specific password](https://support.apple.com/en-us/HT204397)
228
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/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)**
406
407</div>