📧 email-cli

A powerful, feature-complete command-line email client written in Python.
Supports IMAP/SMTP (Gmail, Outlook, QQ, 163, 126, etc.) and Microsoft Exchange (EWS).

---

✨ Features

Feature	IMAP/SMTP	Exchange
List & read emails	✅	✅
Send email (plain/HTML/markdown)	✅	✅
Reply / Reply-all	✅	✅
Forward	✅	✅
Delete	✅	✅
Flag / Star	✅	✅
Move to folder	✅	✅
Full-text search	✅	—
Save attachments	✅	✅
Multiple attachments	✅	✅
List folders	✅	✅
Multiple accounts	✅	✅
Rich terminal UI	✅	✅
Editor integration	✅	✅

---

📦 Installation

# Install from PyPI
pip install email-cli

# Or install from source
git clone https://github.com/hanzhichao/email-cli.git
cd email-cli
pip install -e .

---

🚀 Quick Start

1. Add an account

# IMAP account (Gmail, Outlook, QQ, 163, 126, etc.)
email-cli account add gmail

# Microsoft Exchange account
email-cli account add work --type exchange

The wizard will prompt for:

• Email address
• Password (app password for Gmail/QQ/163/126)
• Server settings (auto-detected for popular providers)

2. List inbox

email-cli list
email-cli list --unread           # unread only
email-cli list --folder Sent      # other folder
email-cli list --limit 50         # show more

3. Read an email

email-cli read 1        # read message #1 from last list
email-cli read 3        # message #3

After reading, you'll see action options: reply, forward, delete, flag.

4. Send email

# Opens your $EDITOR (nano/vim/etc.)
email-cli send --to alice@example.com --subject "Hello"

# Quick send without editor
email-cli send --to alice@example.com --subject "Hi" --body "Hello there!"

# Send HTML email
email-cli send --to alice@example.com --subject "Hello" --body "<h1>Title</h1><p>Message</p>" --html

# Send markdown (converted to HTML)
email-cli send --to alice@example.com --subject "Hello" --body "# Title\n\n**Bold** text" --markdown

# With attachments (can use multiple --attach flags)
email-cli send --to boss@company.com --attach report.pdf --attach data.xlsx

# Combine markdown with attachments
email-cli send --to boss@company.com --subject "Report" --body "# Report\n\nSee attached" --markdown --attach report.pdf

5. Reply & Forward

email-cli reply 3           # reply to message #3
email-cli reply 3 --all     # reply-all
email-cli forward 3 --to colleague@company.com

6. Manage emails

email-cli delete 3                    # delete (with confirmation)
email-cli delete 3 --yes              # skip confirmation
email-cli flag 3                       # flag/star
email-cli flag 3 --unflag             # unflag
email-cli move 3 --dest Archive       # move to folder
email-cli mark 3 read                 # mark as read
email-cli mark 3 unread               # mark as unread

7. Search

email-cli search "meeting notes"
email-cli search --from boss@company.com --unread
email-cli search --subject "invoice" --since "01-Jan-2024"
email-cli search "budget" --folder "Archive"

8. Attachments

email-cli attach 3                    # list attachments
email-cli attach 3 --all              # save all to current directory
email-cli attach 3 --all --dest ~/Downloads
email-cli attach 3 --filename report.pdf --dest ~/Desktop

9. Folders

email-cli folders                     # list all folders with counts

---

⚙️ Configuration

Config file: ~/.email-cli/config.json

Account Management

email-cli account add <name>                  # add new account
email-cli account remove <name>              # remove account
email-cli account list                       # list all accounts
email-cli account default <name>             # set default account
email-cli account test                       # test connection (uses default account)
email-cli account test <name>                # test specific account

Settings

email-cli settings                    # view settings
email-cli settings --set page_size=30
email-cli settings --set editor=vim
email-cli settings --set signature="Best regards,\nJohn"
email-cli settings --set date_format="%d/%m/%Y %H:%M"

Available settings:

Setting	Default	Description
page_size	20	Messages per page
editor	$EDITOR or nano	Editor for composing
signature	(empty)	Auto-appended signature
date_format	%Y-%m-%d %H:%M	Date display format
preview_lines	3	Body preview lines

Multiple accounts

email-cli account add gmail
email-cli account add work --type exchange
email-cli account list
email-cli account default gmail       # set default

# Use specific account
email-cli list --account work
email-cli send --account gmail --to ...

---

📮 Provider Setup

Gmail

1. Enable IMAP in Gmail Settings → Forwarding and POP/IMAP
2. Enable 2FA and generate an App Password: Google Account → Security → App Passwords
3. Use the app password as your password

Email: you@gmail.com
IMAP:  imap.gmail.com:993
SMTP:  smtp.gmail.com:587

Outlook / Hotmail / Office 365

IMAP: outlook.office365.com:993
SMTP: smtp.office365.com:587

QQ Mail (QQ邮箱)

1. Enable IMAP: Settings → Account → POP3/IMAP → Enable
2. Get authorization code (not your QQ password)

IMAP: imap.qq.com:993
SMTP: smtp.qq.com:587

163 / 126 Mail (网易邮箱)

1. 登录网页邮箱 → 设置 → POP3/SMTP/IMAP → 开启 IMAP/SMTP
2. 手机验证码后获取客户端授权码 (16位)
3. 使用授权码作为密码

163:  IMAP: imap.163.com:993  SMTP: smtp.163.com:465 (SSL)
126:  IMAP: imap.126.com:993  SMTP: smtp.126.com:465 (SSL)

Note: 163/126 使用 IMAP ID 命令和 SMTP SSL 端口 465，这是与其他邮箱的主要区别。

Microsoft Exchange

email-cli account add work --type exchange
# Enter EWS URL if known: https://mail.company.com/EWS/Exchange.asmx
# Or leave blank for autodiscover

---

🎨 Terminal UI

With rich installed, you get:

• Color-coded unread/flagged messages
• Beautiful message tables
• Formatted message panels
• Progress indicators

Install rich: pip install rich

---

🔑 Security

• Config file is stored at ~/.email-cli/config.json with chmod 600
• Passwords are stored in plain text — consider using an OS keychain
• For Gmail/QQ/163/126: always use App Passwords/授权码, never your main password

---

📄 License

MIT License