MailToolsBox – Python Email Library

A modern Python email toolkit with SMTP, IMAP, OAuth2, Jinja2 templates, and async support. Secure, reliable, and production-ready.

MailToolsBox is a modern, pragmatic Python library for sending and receiving emails. It unifies SMTP sending and IMAP retrieval in a single package with a clean, consistent API. Designed with security, reliability, and developer experience in mind, it scales from quick scripts to production services.

🌟 Key Features

• SMTP & IMAP Support: Send and receive emails with attachments.
• Security First: TLS, SSL, STARTTLS, and explicit modes (auto, ssl, starttls, none).
• OAuth2 XOAUTH2: Native support for Gmail and Exchange Online authentication.
• Templates: Jinja2 templating with plain text fallback for better deliverability.
• Bulk Sending: Built-in helpers for sending to multiple recipients safely.
• Async & Sync APIs: Use traditional blocking calls or async with asyncio.
• Validation: Email validation and normalization built-in.
• Cross-Platform: Works with Python 3.8+, tested on Linux, macOS, and Windows.

🚀 Installation

pip install MailToolsBox

🔑 Quick Start

Send a basic email

from MailToolsBox import EmailSender

sender = EmailSender(
    user_email="you@example.com",
    server_smtp_address="smtp.example.com",
    user_email_password="password",
    port=587,
    security_mode="starttls"
)

sender.send(
    recipients=["to@example.com"],
    subject="Hello",
    message_body="Plain text body"
)

Read emails

from MailToolsBox.imap_client import ImapClient

with ImapClient(
    email_account="you@example.com",
    password="password",
    server_address="imap.example.com",
    port=993,
    security_mode="ssl"
) as imap:
    imap.select("INBOX")
    uids = imap.search("UNSEEN")
    messages = imap.fetch_many(uids[:10])
    for m in messages:
        print(m.subject, m.from_[0].email if m.from_ else None)

🔒 Security Modes

• auto: Uses SSL on port 465, STARTTLS if available otherwise plain.
• starttls: Forces STARTTLS upgrade.
• ssl: Implicit SSL (typical for port 465).
• none: No TLS, use only in trusted environments.

📧 Advanced Features

• OAuth2 XOAUTH2 for Gmail/Exchange.
• Templates with Jinja2 for dynamic HTML emails.
• Attachments with MIME-smart handling.
• Bulk Sending with privacy safeguards.
• Environment Config for credentials and servers.

📊 Popularity

• 50K+ total downloads on PyPI
• Ranked in the Top 25% of Python packages
• Trusted by developers for automation, integrations, and production systems.

🤝 Contributing

• PRs are welcome (use ruff and black for formatting).
• Please include tests and docs for new features.

📜 License

MIT License — free to use and modify.

MailToolsBox makes email in Python simple, secure, and powerful. Whether you’re automating reports, building integrations, or managing mailboxes, this library gives you all the tools you need.