Himalaya Email Manager

Himalaya Email Manager

Manage emails using Himalaya IMAP CLI tool. Search, summarize, and delete emails from an IMAP account. Use natural language queries for email operations.

Configuration

Himalaya config: ~/.config/himalaya/config.toml Invocation: uv run scripts/<script>.py (handles Python environment and dependencies)

Get Daily Email Summary

Show emails from the past 24 hours in INBOX and Sent folders:

uv run scripts/email-summary.py

Options:

• -v, --verbose - Show himalaya commands being executed

Output includes:

• Rich table format with timestamps, senders, and subjects
• Categorized by folder (📥 INBOX, 📤 Sent)
• Unicode support (Finnish characters, emojis)

Search Emails

Find emails by sender, subject, date range, or folder:

uv run scripts/email-search.py [options]

Options:

• --folder FOLDER - Folder to search (default: INBOX)
• --from SENDER - Filter by sender email/name (case-insensitive)
• --subject TEXT - Filter by subject text (case-insensitive)
• --date-start DATE - Start date (YYYY-MM-DD)
• --date-end DATE - End date (YYYY-MM-DD)
• --limit N - Maximum results (default: 20, capped at 100)
• --no-limit - Bypass the 100-result limit cap
• -v, --verbose - Show himalaya commands being executed
• --help - Show help message

All filters apply with AND logic. Results include message IDs for deletion. Dates must be in YYYY-MM-DD format. FROM filter matches both sender name and email address.

Examples:

# Search by sender
uv run scripts/email-search.py --from "spotify.com"

# Search by subject
uv run scripts/email-search.py --subject "invoice"

# Search by date range
uv run scripts/email-search.py --date-start "2025-12-17" --date-end "2025-12-31"

# Search in Sent folder
uv run scripts/email-search.py --folder Sent --limit 10

# Multiple filters
uv run scripts/email-search.py --from "@newsletter.com" --subject "unsubscribe" --limit 5

# Search with no limit
uv run scripts/email-search.py --limit 200 --no-limit

Save Emails to File

Save email content to a file in various formats:

uv run scripts/email_save.py <message-id> [options]

Options:

• --folder FOLDER - Folder to search (default: INBOX)
• --output PATH - Output directory or file path (default: current directory)
• --format FORMAT - Output format: markdown, text, or json (default: markdown)
• --date-prefix - Add YYYY-MM-DD date prefix to filename (uses email date)
• --download-attachments - Download email attachments
• --attachment-dir PATH - Directory for attachments (default: current directory, same as email save location)
• --overwrite - Overwrite existing file without confirmation
• -v, --verbose - Show himalaya commands being executed
• --help - Show help message

Arguments:

• message-id - Message ID to save (obtained from search results)

Output formats:

• markdown: Rich format with headers and metadata
• text: Plain text with basic headers
• json: Raw JSON output from himalaya (envelope + body data)

Filename behavior:

• Default: {message-id}.{ext}
• With --date-prefix: {YYYY-MM-DD}-{subject-sanitized}.{ext}
• Subject characters: Spaces and emojis preserved, slashes converted to dashes

Examples:

# Save as markdown to current directory
uv run scripts/email_save.py 56873

# Save to specific directory
uv run scripts/email_save.py 56873 --output ~/saved-emails

# Save with date prefix
uv run scripts/email_save.py 56873 --date-prefix --output /tmp/emails

# Save as text format
uv run scripts/email_save.py 56873 --format text

# Save as JSON
uv run scripts/email_save.py 56873 --format json

# Save to specific file path
uv run scripts/email_save.py 56873 --output ~/important-email.md

# Overwrite existing file without prompt
uv run scripts/email_save.py 56873 --overwrite --output ~/email.md

# Save from Sent folder
uv run scripts/email_save.py --folder Sent 12345 --output ~/sent-emails

# Save with attachments
uv run scripts/email_save.py 56873 --download-attachments

# Save with attachments to custom directory
uv run scripts/email_save.py 56873 --download-attachments --attachment-dir ~/attachments

Delete Emails

Delete emails by message ID with safety preview:

uv run scripts/email-delete.py <message-id> [options]

Options:

• --folder FOLDER - Folder to delete from (default: INBOX)
• --execute - Actually perform deletion (default: dry-run mode)
• -v, --verbose - Show himalaya commands being executed
• --help - Show help message

Arguments:

• message-id - Message ID to delete (obtained from search results)

Safety: Always run in dry-run mode first to verify the correct message. In interactive mode, you'll be prompted for confirmation before deletion. When called by OpenCode agent, deletion proceeds immediately with --execute flag.

Examples:

# Preview deletion
uv run scripts/email-delete.py 56838

# Actually delete (interactive - will prompt for confirmation)
uv run scripts/email-delete.py 56838 --execute

# Delete from specific folder
uv run scripts/email-delete.py --folder Sent 12345 --execute

Translate Natural Language Queries

Interpret natural language queries as appropriate script calls:

Summary queries:

• "Show me today's emails" → email-summary.py
• "What emails did I get today?" → email-summary.py
• "Summary of recent emails" → email-summary.py

Search queries:

• "Find emails from Spotify" → email-search.py --from "spotify.com"
• "Show me emails about invoices" → email-search.py --subject "invoice"
• "Search for Atomikettu emails from the past two weeks" → email-search.py --from "atomikettu" --date-start "2025-12-17" --date-end "2025-12-31"
• "What did I send yesterday?" → email-search.py --folder Sent --date-start "2025-12-30" --date-end "2025-12-30"
• "Search INBOX for emails from john@example.com" → email-search.py --from "john@example.com"
• "Find emails with 'newsletter' in subject" → email-search.py --subject "newsletter"

Save queries:

• "Save email ID 56873" → email_save.py 56873
• "Save as JSON" → email_save.py 56873 --format json
• "Save to ~/emails folder with date prefix" → email_save.py 56873 --output ~/emails --date-prefix

Delete queries:

• "Delete email ID 56838" → email-delete.py 56838 (show preview, ask for confirmation)
• "Remove the email from Spotify" → First search to find ID, then delete with confirmation

Implementation Notes

When calling scripts:

1. Always invoke with uv run scripts/<script-name>.py (handles environment and deps)
2. For search by sender or subject, use --from and --subject flags
3. Date range uses --date-start and --date-end (YYYY-MM-DD format)
4. Case-insensitive search is automatic - don't worry about capitalization
5. FROM filter searches both sender name and email address
6. Always run delete operations in dry-run mode first without --execute flag
7. Ask user for confirmation before running delete with --execute flag (interactive mode only)
8. Use -v/--verbose to see himalaya commands being executed (for debugging)

Avoid these pitfalls:

• Don't use --since or --until (not implemented - use --date-start/--date-end)
• Don't try to search body content (only headers are available in JSON output)
• Don't forget to add --execute flag when actually deleting (dry-run by default)
• Don't use incorrect date format (must be YYYY-MM-DD)

Follow this workflow for search and delete:

1. Use email-search.py to find messages
2. Review results with user
3. Use email-delete.py to preview deletion
4. Get user confirmation
5. Use email-delete.py --execute to actually delete

Technical context:

• Backend: Himalaya v1.1.0 (Rust-based IMAP CLI tool) via Python 3.13 with typer and rich
• Installation: Himalaya must be installed on your system
• Output format: JSON → Rich tables with Python json.loads()
• Authentication: Keyring-based (managed by Himalaya)
• Protocol: IMAP over TLS (direct server communication)
• Date format: YYYY-MM-DD (ISO 8601)
• Case sensitivity: All search filters are case-insensitive using Python .lower()
• Agent detection: Uses sys.stdin.isatty() to determine if running interactively

Using the Scripts

All scripts use PEP 723 inline metadata and require Python 3.13+. Invoke with uv run to automatically handle Python environment and dependencies:

uv run scripts/<script-name>.py [options]

Dependencies (auto-managed by uv):

• typer - for CLI argument parsing
• rich - for beautiful terminal output