Metadata-Version: 2.4
Name: python-email-cli
Version: 0.1.0
Summary: A powerful command-line email client supporting IMAP/SMTP and Exchange
Home-page: https://github.com/hanzhichao/email-cli
Author: Hanzhichao
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Topic :: Communications :: Email
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: markdown-it-py>=3.0.0
Provides-Extra: exchange
Requires-Dist: exchangelib>=5.0.0; extra == "exchange"
Provides-Extra: all
Requires-Dist: exchangelib>=5.0.0; extra == "all"
Requires-Dist: rich>=13.0.0; extra == "all"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 📧 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)**.

![Language - Python](https://img.shields.io/badge/language-python-blue.svg)
![PyPI - License](https://img.shields.io/pypi/l/python-email-cli)
![PyPI](https://img.shields.io/pypi/v/python-email-cli)
![PyPI - Downloads](https://img.shields.io/pypi/dm/python-email-cli)

---

## ✨ 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

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
email-cli folders                     # list all folders with counts
```

---

## ⚙️ Configuration

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

### Account Management

```bash
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

```bash
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

```bash
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
```bash
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
