A CLI tool that connects to Gmail via IMAP and generates statistics about email distribution by recipient address. Designed for catch-all inbox analysis.
- Connect to Gmail via IMAP with App Password authentication
- Generate statistics by recipient (
to) address - Interactive TUI for email triage with batch archiving
- List all mailboxes/labels in your account
- Special handling for catch-all addresses (admin@, hi@, email@) - groups by sender instead
- Multiple output formats: table, JSON, CSV
- Flexible configuration: CLI flags, environment variables, config file
- Secure password storage using OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
go install github.com/josegonzalez/gmail-categorizer/cmd/gmail-categorizer@latestOr build from source:
git clone https://github.com/josegonzalez/gmail-categorizer.git
cd gmail-categorizer
make build- Go to Google Account Security
- Enable 2-Step Verification if not already enabled
- Go to App Passwords
- Select "Mail" and your device, then click "Generate"
- Copy the 16-character password
The CLI has three subcommands: stats, triage, and mailboxes.
Generate statistics about email distribution:
# Interactive password prompt
gmail-categorizer stats -u your-email@gmail.com
# With environment variable
export GMAIL_CATEGORIZER_IMAP_PASSWORD="your-app-password"
gmail-categorizer stats -u your-email@gmail.com
# With config file
gmail-categorizer stats -c ~/.gmail-categorizer.yaml
# Different output formats
gmail-categorizer stats -u your-email@gmail.com -f json
gmail-categorizer stats -u your-email@gmail.com -f csv > stats.csvInteractive TUI for batch email management:
# Launch triage interface
gmail-categorizer triage -u your-email@gmail.com -k
# With keychain (recommended for repeated use)
gmail-categorizer triage -u your-email@gmail.com --keychainThe triage interface allows you to:
- View emails grouped by recipient address
- Browse subject lines within each group
- Archive entire groups with a single action
When archiving, emails are moved to automated/<local_part> folders based on the grouping address. For example, emails grouped under notifications@example.com are archived to the automated/notifications folder.
List all available mailboxes/labels:
gmail-categorizer mailboxes -u your-email@gmail.com -kStore your password securely in the OS keychain to avoid entering it each time:
# First run: prompts for password and stores it in keychain
gmail-categorizer stats -u your-email@gmail.com --keychain
# Subsequent runs: retrieves password from keychain automatically
gmail-categorizer stats -u your-email@gmail.com --keychain
# Store password from environment variable in keychain
GMAIL_CATEGORIZER_IMAP_PASSWORD="your-app-password" gmail-categorizer stats -u your-email@gmail.com --keychain
# Delete stored password from keychain
gmail-categorizer stats -u your-email@gmail.com --delete-keychainThe keychain feature uses:
- macOS: Keychain Access
- Windows: Windows Credential Manager
- Linux: Secret Service (GNOME Keyring, KWallet)
Global flags:
-c, --config string config file (default: $HOME/gmail-categorizer.yaml)
-h, --help help for gmail-categorizer
-v, --version version for gmail-categorizer
Stats command flags:
-u, --username string Gmail username/email address
-p, --password string Gmail app password (prefer stdin or env var)
-m, --mailbox string mailbox to analyze (default "INBOX")
-k, --keychain use OS keychain to store/retrieve password
--delete-keychain delete stored password from keychain and exit
-f, --format string output format: table, json, csv (default "table")
-l, --limit int limit number of results (0 = unlimited)
--sort-by string sort by: count, address (default "count")
--sort-order string sort order: asc, desc (default "desc")
Triage command flags:
-u, --username string Gmail username/email address
-p, --password string Gmail app password (prefer stdin or env var)
-k, --keychain use OS keychain to store/retrieve password
--delete-keychain delete stored password from keychain and exit
Mailboxes command flags:
-u, --username string Gmail username/email address
-p, --password string Gmail app password (prefer stdin or env var)
-k, --keychain use OS keychain to store/retrieve password
Configuration can be provided via:
- CLI flags (highest priority)
- Environment variables
- Config file
- Defaults (lowest priority)
export GMAIL_CATEGORIZER_IMAP_USERNAME="your-email@gmail.com"
export GMAIL_CATEGORIZER_IMAP_PASSWORD="your-app-password"
export GMAIL_CATEGORIZER_OUTPUT_FORMAT="json"Create ~/.gmail-categorizer.yaml or ./gmail-categorizer.yaml:
imap:
username: your-email@gmail.com
# password: set via env var or stdin for security
mailbox: INBOX
output:
format: table
sort_by: count
sort_order: desc
limit: 0
special:
group_by_from:
- admin@
- hi@
- email@
- support@For catch-all inboxes, emails to certain addresses (like admin@, hi@, email@) are grouped by sender instead of recipient. This helps identify who is sending emails to these generic addresses.
Example output:
Emails by Recipient Address:
+----------------------+-------+
| To Address | Count |
+----------------------+-------+
| user@yourdomain.com | 150 |
| sales@yourdomain.com | 75 |
+----------------------+-------+
| Total | 225 |
+----------------------+-------+
Emails to Special Addresses (grouped by sender):
+----------------------+----------------------+-------+
| To Address | From Address | Count |
+----------------------+----------------------+-------+
| admin@yourdomain.com | noreply@service.com | 45 |
| admin@yourdomain.com | alerts@monitor.io | 23 |
| hi@yourdomain.com | newsletter@news.com | 12 |
+----------------------+----------------------+-------+
# Run tests
make test
# Build
make build
# Format code
make fmt
# Run all checks
make allMIT