Metadata-Version: 2.4
Name: YIYIMail
Version: 1.0.1
Summary: A high-performance, modern Python library for email processing (IMAP/POP3/SMTP).
Author: Aquarius-0455
Project-URL: Homepage, https://github.com/Aquarius-0455/YIYI-Mail
Project-URL: Bug Tracker, https://github.com/Aquarius-0455/YIYI-Mail/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <img src="YIYIMail_logo.png" alt="YIYIMail Logo" width="200">
</p>

# YIYIMail 🚀

[中文说明](README_CN.md) | English Version


YIYIMail is a high-performance, modern Python library for email processing. It is designed to replace legacy libraries by providing seamless support for IMAP, POP3, and SMTP, featuring high-performance server-side search, elegant HTML/CID parsing, and extreme ease of use.

## 🌟 Key Features

- **Modern Protocol Support**: Full support for IMAP, POP3, and SMTP. Auto-identification for personal (Gmail, Outlook, 163, QQ) and Enterprise providers (Tencent, Ali, Netease).
- **High-Performance Search**: Leverage IMAP server-side search to locate emails instantly. Filter by **Subject, Sender, Date, and Unseen status** with **limit** support.
- **Superior Compatibility**: Built-in IMAP `ID` command support to pass security checks of providers like 163.com and Tencent.
- **Smart Folder Matching**: Automatically handles Modified UTF-7 encoding for non-ASCII folder names. Supports direct use of localized names like "已发送" or "Sent Messages".
- **Elegant Parser**: Automatically handles CID inline images and generates Base64-rendered HTML for perfect offline viewing.
- **Utility Toolbox**: Built-in `show()` for pretty printing and `save()`/`load()` for local persistence.
- **Type Safe**: Fully typed with Python 3.7+ type hints.

## 📦 Installation

```bash
# Just copy the YIYIMail folder into your project.
import YIYIMail
```

## 🚀 Quick Start

### 1. Connection
YIYIMail automatically identifies server settings based on your email domain.

```python
import YIYIMail

# Use authorization codes for services like 163, QQ, etc.
mail = YIYIMail.connect('your_name@163.com', 'your_auth_code')

# Enterprise mail support (Auto-detects Tencent, Ali, Netease)
# mail = YIYIMail.connect('admin@exmail.qq.com', 'password')

# Or manual server configuration
# mail = YIYIMail.connect('user@company.com', 'pwd', smtp_host='smtp.company.com', imap_host='imap.company.com')
```

### 2. Send Emails
Supports multiple recipients, attachments, and HTML content.

```python
mail.send(
    recipients=['friend@example.com'],
    subject='Hello',
    content='This is a test email',
    html='<h1>Hello</h1><p>Sent via YIYIMail!</p>',
    attachments=['/path/to/report.pdf']
)
```

### 3. Advanced Search (IMAP)
Search on the server without downloading everything.

```python
# Search for emails after May 1st, 2026, limit to 5 latest results
results = mail.search(after='2026-05-01', subject='Report', limit=5)

# Search for unseen emails from a specific sender
unread = mail.search(sender='boss@company.com', unseen=True)

# Search in a specific folder
sent = mail.search(subject='Project', folder='Sent Messages')
```

### 4. Fetch & Display
```python
# Get the latest email
latest = mail.fetch_latest()

# Get a range of emails
mails = mail.fetch_mails(start=1, end=10)

# Pretty print content to console
YIYIMail.show(latest)
```

### 5. Status Management
```python
uid = latest['uid']
mail.mark_as_read(uid)    # Mark as seen
mail.mark_as_unread(uid)  # Mark as unseen
```

### 6. Persistence
```python
# Save to local JSON
YIYIMail.save(latest, 'my_mail.json')

# Load from local
local_mail = YIYIMail.load('my_mail.json')
```

### 7. Mailbox Information
```python
# Get mailbox statistics (total count, size)
stats = mail.info()
print(f"Total Mails: {stats['count']}, Size: {stats['size_bytes']} bytes")
```

## 🛠️ Folder Management
Use `mail.folders()` to get decoded folder names from the server.

```python
print(mail.folders()) 
# Output: ['INBOX', 'Drafts', 'Sent Messages', 'Trash', ...]
```

## ⚖️ License
MIT License
