https://github.com/guiyumin/maily
a handy email client, and more
https://github.com/guiyumin/maily
apple claude claude-code cli codex email gemini-cli gmail icalendar macbook mistral ollama
Last synced: 11 days ago
JSON representation
a handy email client, and more
- Host: GitHub
- URL: https://github.com/guiyumin/maily
- Owner: guiyumin
- License: other
- Created: 2025-12-19T05:17:10.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-01-28T19:09:30.000Z (19 days ago)
- Last Synced: 2026-01-28T23:09:25.912Z (19 days ago)
- Topics: apple, claude, claude-code, cli, codex, email, gemini-cli, gmail, icalendar, macbook, mistral, ollama
- Language: TypeScript
- Homepage: https://MailySuite.com
- Size: 2.36 MB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Maily
A fast, keyboard-driven terminal email client with calendar integration.
## Features
- **Multi-account support** - Gmail, Yahoo, and custom IMAP providers
- **Fast startup** - Local caching with background sync server
- **Keyboard-driven interface** - Vim-inspired navigation, command palette
- **Email operations** - Compose, reply, delete, search, folder/label navigation
- **Calendar integration** - macOS EventKit with natural language event creation
- **AI summarization** - Email summaries via Claude, Codex, Gemini, Ollama, or BYOK
- **Today view** - Combined view of emails and calendar events
- **Bulk actions** - Multi-select in search results for batch operations
- **Self-update** - Built-in update mechanism
## Platforms
- **macOS** - Full features including calendar integration
- **Linux** - All features except calendar (no EventKit)
## Installation
### Homebrew (macOS/Linux)
```bash
brew install guiyumin/tap/maily
```
### From Source
```bash
git clone https://github.com/guiyumin/maily.git
cd maily
make build
./build/maily
```
### Self-Update
```bash
maily update
```
## Quick Start
1. Add your email account:
```bash
maily login gmail # For Gmail
maily login yahoo # For Yahoo
maily login qq # For qq mail
```
2. Start the TUI:
```bash
maily
```
The background server starts automatically when you open maily.
## Key Bindings
See [docs/keybindings.md](docs/keybindings.md) for the full list of key bindings.
## Commands
```bash
# Email
maily # Start TUI
maily login gmail # Add Gmail account
maily login yahoo # Add Yahoo account
maily login qq # Add qq mail account
maily logout # Remove account
maily accounts # List accounts
maily sync # Manual full sync
# Search (-a required if multiple accounts)
maily search -a me@gmail.com -q "from:temu" # Interactive TUI search
maily search -q "is:unread" --count # Count matching emails
maily search -q "from:amazon" --format=json --limit=50
maily search -q "has:attachment" --format=table
# Calendar (macOS)
maily calendar # Calendar TUI
maily c # Short alias
maily c list # List available calendars
maily c add "..." # Create event with natural language
# Today View
maily today # Combined email + calendar view
maily t # Short alias
# Server
maily server status # Check server status
maily server stop # Stop the server
maily server start # Start server manually
# Configuration
maily config # Interactive config TUI
# Maintenance
maily update # Update to latest version
maily version # Show version info
```
## Configuration
Configuration is stored in `~/.config/maily/`:
- `accounts.yml` - Email accounts and credentials
- `config.yml` - Application settings
- `maily.db` - Email cache (SQLite)
- `server.pid` - Background server PID
### Settings
```yaml
# ~/.config/maily/config.yml
max_emails: 50 # Emails to load per page
default_label: INBOX # Default folder
theme: default # UI theme
# AI accounts (OpenAI-compatible API)
ai_accounts:
- name: openai
base_url: https://api.openai.com/v1
api_key: sk-...
model: gpt-4o-mini
```
## Gmail Setup
1. Enable 2-Factor Authentication on your Google account
2. Generate an App Password: Google Account > Security > App Passwords
3. Use the 16-character App Password when running `maily login gmail`
## Yahoo Setup
1. Enable 2-Factor Authentication on your Yahoo account
2. Generate an App Password: Account Security > Generate app password
3. Use the App Password when running `maily login yahoo`
See [docs/features/yahoo-mail.md](docs/features/yahoo-mail.md) for detailed instructions.
## AI Integration
Maily supports AI-powered features through multiple providers:
- **CLI tools**: Claude, Codex, Gemini, Ollama (auto-detected)
- **BYOK (Bring Your Own Key)**: Any OpenAI-compatible API (configure in `config.yml`)
Features:
- Email summarization (`s` key in read view)
- Natural language calendar event creation (`n` key in calendar)
- Event extraction from emails
## Architecture
- Built with Go and [Bubbletea](https://github.com/charmbracelet/bubbletea) (Elm-architecture TUI framework)
- Uses [go-imap/v2](https://github.com/emersion/go-imap) for IMAP and SMTP
- Local cache for fast startup, background server for sync (30-min interval)
- No optimistic UI - server operations wait for confirmation
- macOS calendar via EventKit (CGO)
## License
[Apache 2.0](LICENSE)