Skip to content

USAGE.md

Latest commit

 

History

History
540 lines (390 loc) · 11.1 KB

USAGE.md

File metadata and controls

540 lines (390 loc) · 11.1 KB

Usage Guide

Complete guide to using mailcli for email management.

Table of Contents

  1. Configuration
  2. Listing Emails
  3. Searching Emails
  4. Viewing Emails
  5. Multiple Accounts
  6. Scripting Examples
  7. Advanced Tips

Configuration

Initial Setup

mailcli config add

The setup is now simplified to just 2 steps:

  1. Enter email address - Provider is auto-detected
  2. Enter password - Done! ✓

Example:

$ mailcli config add
Email address: user@gmail.com
✓ Detected provider: Gmail
Password (or app-specific password): ********
✓ Configuration saved!

📧 Account: Gmail (user@gmail.com)
🔗 Provider: Gmail

Supported providers (auto-detected from email):

  • Gmail (@gmail.com)
  • Outlook (@outlook.com)
  • QQ Mail (@qq.com)
  • 163/126 Mail (@163.com, @126.com)
  • Yahoo Mail (@yahoo.com)
  • iCloud (@icloud.com, @me.com)

For custom IMAP servers or detailed configuration options, see CONFIG_SIMPLIFICATION.md.

List Accounts

mailcli config list

Output:

Accounts:
* gmail (user@gmail.com) - default
  work (user@company.com)

Test Connection

# Test default account
mailcli config test

# Test specific account
mailcli config test --account work

Set Default Account

mailcli config set-default

Select from the list of configured accounts.

Remove Account

mailcli config remove

Select the account to remove from the list.

Listing Emails

Basic List

# List recent emails (default: 20)
mailcli mail list

# List more emails
mailcli mail list --limit 50

# List with offset (pagination)
mailcli mail list --limit 20 --offset 20

Output (text format):

[12345] john@example.com: Project Update (2024-03-19 10:30)
[12346] meeting@company.com: Weekly Sync (2024-03-19 09:00)
[12347] newsletter@news.io: Daily Digest (2024-03-19 08:15)

List from Specific Folder

# List from Sent folder
mailcli mail list --folder "Sent"

# List from Archive
mailcli mail list --folder "Archive"

# List from custom folder
mailcli mail list --folder "Projects/Active"

Different Output Formats

# Table format
mailcli mail list --output table

# JSON format
mailcli mail list --output json

Table output:

┌───────────┬────────────────────┬──────────────────┬──────────────────────┐
│ UID       │ FROM               │ SUBJECT          │ DATE                 │
├───────────┼────────────────────┼──────────────────┼──────────────────────┤
│ 12345     │ john@example.com   │ Project Update   │ 2024-03-19 10:30     │
│ 12346     │ meeting@company.com│ Weekly Sync      │ 2024-03-19 09:00     │
└───────────┴────────────────────┴──────────────────┴──────────────────────┘

Searching Emails

Basic Search

# Search unread emails
mailcli mail search --unread

# Search read emails
mailcli mail search --read

# Search flagged emails
mailcli mail search --flagged

Search by Sender/Recipient

# Search from specific sender
mailcli mail search --from "john@example.com"

# Search to specific recipient
mailcli mail search --to "me@company.com"

# Partial match works too
mailcli mail search --from "john"

Search by Content

# Search by subject
mailcli mail search --subject "project"

# Search by body content
mailcli mail search --body "meeting"

# Combine subject and body
mailcli mail search --subject "urgent" --body "deadline"

Search by Date

# Search emails since a date
mailcli mail search --since 2024-01-01

# Search emails before a date
mailcli mail search --before 2024-12-31

# Date range
mailcli mail search --since 2024-01-01 --before 2024-03-31

# Recent emails (last 7 days)
mailcli mail search --since $(date -d '7 days ago' +%Y-%m-%d)

Search by Status Flags

# Unread emails
mailcli mail search --unread

# Read emails
mailcli mail search --read

# Flagged emails
mailcli mail search --flagged

# Answered emails
mailcli mail search --answered

# Draft emails
mailcli mail search --draft

# Deleted emails
mailcli mail search --deleted

# Recent emails
mailcli mail search --recent

# With attachments
mailcli mail search --has-attachment

Complex Searches

# Unread emails from boss
mailcli mail search --unread --from "boss@company.com"

# Flagged emails this week
mailcli mail search --flagged --since 2024-03-13

# Important emails from multiple senders
mailcli mail search --subject "urgent" --flagged --unread

# Large attachments
mailcli mail search --has-attachment --since 2024-01-01

Limit and Offset

# Limit results
mailcli mail search --unread --limit 10

# Pagination
mailcli mail search --from "newsletter" --limit 20 --offset 20

Viewing Emails

View Email Details

# View email by UID
mailcli mail get 12345

Output:

From: john@example.com
To: user@gmail.com
Subject: Project Update
Date: 2024-03-19 10:30:45

Body:
Hi,

Just wanted to give you an update on the project...

Best,
John

View as JSON

# View email as JSON
mailcli mail get 12345 --format json

# Pretty print with jq
mailcli mail get 12345 --format json | jq

View from Specific Account

# Use specific account
mailcli --account work mail get 54321

Multiple Accounts

Add Multiple Accounts

# Initialize first account
mailcli config add

# Add second account (just run init again)
mailcli config add

Switch Between Accounts

# Use specific account for one command
mailcli --account work mail list
mailcli --account personal mail search --unread

# Set default account
mailcli config set-default

# List all accounts
mailcli config list

Scripting with Multiple Accounts

# Check unread emails across all accounts
for account in personal work; do
  echo "=== $account ==="
  mailcli --account "$account" mail search --unread --output json | jq -r '.[].subject'
done

Scripting Examples

Count Unread Emails

# Count unread
mailcli mail search --unread --output json | jq 'length'

# Count unread across accounts
for account in $(mailcli config list --output json | jq -r '.[].name'); do
  count=$(mailcli --account "$account" mail search --unread --output json | jq 'length')
  echo "$account: $count unread"
done

Extract Senders

# Get unique senders
mailcli mail list --limit 100 --output json | \
  jq -r '.[].from' | sort | uniq -c | sort -rn

Find Large Emails

# Find emails with attachments (potential large files)
mailcli mail search --has-attachment --output json | \
  jq 'select(.size > 1000000)'

Backup Email Headers

# Export email headers to CSV
mailcli mail list --output json | \
  jq -r '.[] | [.uid, .from, .subject, .date] | @csv' > emails.csv

Monitor for New Emails

# Watch for new emails (check every 60 seconds)
while true; do
  count=$(mailcli mail search --unread --output json | jq 'length')
  echo "$(date): $count unread emails"
  sleep 60
done

Batch Operations

# Mark all newsletter emails as read (conceptual - requires IMAP STORE)
mailcli mail search --from "newsletter@" --output json | \
  jq -r '.[].uid' | while read uid; do
    # Would need IMAP STORE command to mark as read
    echo "Would mark email $uid as read"
  done

Advanced Tips

Use with cron

# Add to crontab to check unread emails every hour
crontab -e

# Add line:
0 * * * * /usr/local/bin/mailcli mail search --unread --output json | jq 'length' > /tmp/unread_count.txt

Create Aliases

Add to ~/.bashrc or ~/.zshrc:

# Quick aliases
alias unread='mailcli mail search --unread'
alias inbox='mailcli mail list --limit 20'
alias sent='mailcli mail list --folder "Sent"'
alias workmail='mailcli --account work mail list'
alias personalmail='mailcli --account personal mail list'

Use with fzf (fuzzy finder)

# Interactive email search
mailcli mail list --output json | \
  jq -r '.[] | "\(.uid) \(.from) \(.subject)"' | \
  fzf | \
  awk '{print $1}' | \
  xargs mailcli mail get

Pipe to less for Pagination

# View long email lists
mailcli mail list --limit 100 | less

# View email body with pagination
mailcli mail get 12345 | less

Colorize Output

# Colorize JSON output
mailcli mail list --output json | jq -C

# Colorize with grc (generic colouriser)
mailcli mail list | grc cat

Performance Tips

Limit Search Scope

# Faster: use specific folder
mailcli mail search --folder "INBOX" --unread

# Slower: search all folders
mailcli mail search --unread

Use Pagination

# Fetch in batches
mailcli mail list --limit 100 --offset 0
mailcli mail list --limit 100 --offset 100
mailcli mail list --limit 100 --offset 200

Cache Results

# Save to file for reuse
mailcli mail search --unread --output json > /tmp/unread.json

# Use cached file
jq '.[].subject' /tmp/unread.json

Troubleshooting

Slow Searches

Problem: Search is slow with many emails.

Solution:

  1. Use more specific filters (date range, sender)
  2. Limit folder scope
  3. Use pagination

Connection Errors

Problem: "connection refused" or "timeout".

Solution:

  1. Test connection: mailcli config test
  2. Check network connectivity
  3. Verify firewall settings
  4. Check IMAP server status

Authentication Failed

Problem: "authentication failed".

Solution:

  1. Use app-specific password for Gmail
  2. Enable IMAP in account settings
  3. Verify username and password
  4. Check for account locks

Empty Results

Problem: Search returns no results.

Solution:

  1. Check if folder exists: mailcli mail list --folder "All Mail"
  2. Verify search criteria
  3. Try broader search first
  4. Check account permissions

Best Practices

  1. Use app-specific passwords for Gmail/Yahoo
  2. Enable IMAP in email provider settings
  3. Use JSON output for scripting
  4. Set default account if using multiple accounts
  5. Use specific folders to improve performance
  6. Limit results for large mailboxes
  7. Test connection after configuration changes
  8. Keep binary updated for bug fixes and features

Further Reading