YIYIMail 🚀

中文说明 | 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

pip install YIYIMail

🚀 Quick Start

1. Connection

YIYIMail automatically identifies server settings based on your email domain.

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.

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.

# 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

# 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

uid = latest['uid']
mail.mark_as_read(uid)    # Mark as seen
mail.mark_as_unread(uid)  # Mark as unseen

6. Persistence

# Save to local JSON
YIYIMail.save(latest, 'my_mail.json')

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

7. Mailbox Information

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

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

⚖️ License

MIT License