mailcli

A universal email command-line interface tool that supports all email providers via IMAP protocol.

English | 简体中文

Features

• Universal Support: Works with any IMAP-compatible email service
• Multi-Account: Manage multiple email accounts seamlessly
• Powerful Search: Search by sender, recipient, subject, body, text, date, and flags
• Flexible Output: Text, table, and JSON formats for scripting
• Secure: TLS/SSL encryption, application-specific passwords
• AI-Friendly: Non-interactive configuration and JSON output for AI agents

Quick Start

Installation

# Linux/macOS (auto-detect latest version)
VERSION=$(curl -s https://api.github.com/repos/keepmind9/mailcli/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
curl -L https://github.com/keepmind9/mailcli/releases/download/$VERSION/mailcli-linux-amd64.tar.gz | tar -xz
mkdir -p ~/.local/bin && mv mailcli-linux-amd64 ~/.local/bin/mailcli

→ Full Installation Guide

Basic Usage

# 1. Add email account
mailcli config add

# 2. List recent emails
mailcli mail list

# 3. Search unread emails
mailcli mail search --unread

# 4. Search by sender
mailcli mail search --from "boss@company.com"

# 5. Search in entire email (headers + body)
mailcli mail search --text "project update"

# 6. View email content
mailcli mail get 12345

Common Use Cases

Check Unread Emails

# List unread emails
mailcli mail search --unread

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

# Unread emails with keyword
mailcli mail search --unread --subject "urgent"

Search Emails

# By subject
mailcli mail search --subject "project"

# By body content
mailcli mail search --body "meeting"

# By entire email content (headers + body)
mailcli mail search --text "invoice"

# By date range
mailcli mail search --since 2024-01-01 --before 2024-12-31

# Combine multiple filters
mailcli mail search --unread --from "boss@company.com" --subject "project"

Manage Emails

# List with JSON output (for scripts/AI)
mailcli mail list --output json

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

# List flagged emails
mailcli mail search --flagged

# List with limit
mailcli mail list --limit 50

Non-Interactive Configuration (AI Agents)

# Auto-detect provider
mailcli config add --email "user@gmail.com" --password "app-password"

# QQ Mail (use authorization code, not QQ password)
mailcli config add --email "user@qq.com" --password "authorization-code" --provider "qq"

# Custom IMAP server
mailcli config add --email "user@company.com" --password "password" \
  --host "imap.company.com" --port 993 --tls

# Use environment variable for password (recommended)
export MAILCLI_PASSWORD_PERSONAL="your-app-password"
mailcli config add --email "user@gmail.com" --name "personal"

Supported Providers

mailcli works with any IMAP-compatible email service. Popular providers include:

• Custom IMAP server (any IMAP-compatible service)
• Gmail
• Outlook / Office365
• QQ Mail
• 163 / 126 Mail
• Yahoo Mail
• iCloud
• Tencent Exmail
• Aliyun Enterprise
• NetEase Enterprise

Note: While mailcli is designed to work with all IMAP-compatible servers, we have only tested with a subset of providers (163 Mail, Tencent Exmail). If you encounter any issues with your email provider, please report them - we'd love to make mailcli work for everyone!

Output Formats

# Table format (default)
mailcli mail list

# JSON format (for scripts/AI)
mailcli mail search --unread --output json

# Text format
mailcli mail get 12345 --output text

AI Agent Integration

mailcli includes a dedicated Claude AI skill that enables AI agents to manage emails automatically.

Installation

The skill will auto-install when first used, or manually:

# Linux/macOS
bash <(curl -s https://raw.githubusercontent.com/keepmind9/mailcli/main/scripts/install.sh)

# Windows
powershell -ExecutionPolicy Bypass -File scripts/install.ps1

For AI Agents

# 1. Non-interactive configuration (no prompts)
mailcli config add --email "user@gmail.com" --password "app-password"

# 2. Always use JSON output for machine parsing
mailcli mail search --unread --output json

# 3. Search with specific filters
mailcli mail search --from "boss@company.com" --subject "urgent" --output json

Key Features for AI Agents

• Non-interactive mode: No prompts, fully automated configuration
• JSON output: Structured data for easy parsing
• Comprehensive search: By sender, recipient, subject, body, text, date, flags
• Auto-installation: Skill detects and installs mailcli if needed
• Multi-platform support: Works on Linux, macOS, and Windows

Learn more: mailcli Skill Documentation

Command Reference

Configuration Commands

mailcli config add          # Add email account
mailcli config list          # List all accounts
mailcli config test          # Test connection
mailcli config remove        # Remove account

Mail Commands

mailcli mail list            # List emails
mailcli mail search          # Search emails
mailcli mail get <uid>       # View email

Search Options

Option	Description
--unread	Only unread messages
--read	Only read messages
--flagged	Only flagged messages
--answered	Only answered messages
--draft	Only draft messages
--deleted	Only deleted messages
--recent	Only recent messages
--from <email>	From sender
--to <email>	To recipient
--subject <text>	Subject contains text
--body <text>	Body contains text
--text <text>	Headers + body contains text
--since <date>	Since date (YYYY-MM-DD)
--before <date>	Before date (YYYY-MM-DD)
--has-attachment	With attachments
--limit <num>	Number of results (default: 20)
--offset <num>	Offset for pagination
--sort-by <field>	Sort field (date, from, subject, size)
--order <order>	Sort order (asc, desc)
--latest	Show newest first (shorthand for --order desc)
--folder <name>	Folder name (default: INBOX)
--output json	JSON format for AI parsing

Configuration

Configuration is stored in ~/.config/mailcli/config.yaml:

accounts:
  - name: personal
    email: user@gmail.com
    username: user@gmail.com
    password: your-password  # Or use environment variable (see below)
    host: imap.gmail.com
    port: 993
    use_tls: true

Environment Variable Password (Recommended)

For better security, you can store passwords in environment variables instead of the config file:

# Set password as environment variable
export MAILCLI_PASSWORD_PERSONAL="your-app-password"

# mailcli will automatically use the environment variable
mailcli mail search --unread

Environment variable format: MAILCLI_PASSWORD_<ACCOUNT_NAME> (account name converted to uppercase)

Priority: Environment variable takes priority over config file password

Account name requirements: Only letters, numbers, hyphens (-), and underscores (_) are allowed

Examples:

• Account name personal → Environment variable MAILCLI_PASSWORD_PERSONAL
• Account name work-account → Environment variable MAILCLI_PASSWORD_WORK_ACCOUNT
• Account name my_gmail → Environment variable MAILCLI_PASSWORD_MY_GMAIL

→ Full Documentation

Troubleshooting

Connection Issues

# Test connection
mailcli config test

# Enable verbose logging
mailcli --verbose mail search --unread

Gmail Issues

Gmail requires an App Password:

1. Enable 2-Factor Authentication
2. Generate App Password
3. Use App Password in mailcli

Outlook Issues

Enable IMAP in Outlook settings.

QQ/163 Mail Issues

QQ Mail and 163/126 Mail require an authorization code (授权码), not your login password:

1. Login to your email provider's web interface
2. Go to Settings → Account (设置 → 账户)
3. Enable IMAP/SMTP service
4. Generate authorization code (16 characters)
5. Use the authorization code in mailcli

For detailed steps, refer to your email provider's official documentation.

More Documentation

• Installation Guide - Detailed installation instructions
• Contributing - How to contribute
• Development - Development guide
• Usage Examples - More usage examples
• FAQ - Frequently asked questions
• CHANGELOG.md - Version history

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT License