Welcome to email-profile¶
A Python library for email management. Connect to any IMAP/SMTP server, read and send emails, sync your mailbox to a local database, and restore backups — all with a single, unified API. Or hand the same account to Claude, Cursor or any MCP client with the built-in MCP server.
"""Read your unread mail in 4 lines."""
from email_profile import Email
def main() -> None:
with Email.from_env() as app:
for msg in app.unread().messages():
print(f"{msg.date} {msg.from_:<40} {msg.subject}")
if __name__ == "__main__":
main()
Start with the basics here, or go straight to the MCP server.
Features¶
| Feature | Description |
|---|---|
| Auto-discovery | Detects IMAP/SMTP servers from email domain (50+ providers) |
| Unified API | IMAP + SMTP in a single Email class |
| Query Builder | Composable search with Q (AND, OR, NOT) and validated Query kwargs |
| Sync | Incremental backup from server to SQLite with progress bars |
| Restore | Upload emails back to server with duplicate detection |
| Parallel | Multi-threaded sync and restore with configurable workers |
| Progress | Rich progress bars with per-mailbox status |
| Retry | Exponential backoff on transient failures |
| Send | Send, reply, forward with HTML and attachments |
| Storage | Pluggable storage backend (SQLite default) |
| Flags | Read/unread, flag, delete, move, copy operations |
| Context Manager | with Email(...) as app: for automatic cleanup |
| MCP Server | 14 tools + 4 prompts for Claude Code, Claude Desktop, Cursor — read-only until you opt in |
| Plugin | Claude Code plugin with skills that gate sending behind your approval |
Getting Help¶
We use GitHub issues for tracking bugs and feature requests.
License¶
This project is licensed under the terms of the MIT license.