MailToolsBox is a pragmatic email toolkit built for real-world Python automation. It combines reliable SMTP sending and a capable IMAP client under a unified, clean API. The library is designed around explicit security choices, predictable defaults, and extensibility.

Whether you are sending one message, generating templated notifications, reading mailbox contents, or exporting entire folders, MailToolsBox provides a consistent, well-tested interface backed by stable protocols and optional modern features such as OAuth2 XOAUTH2 authentication.

SMTP sending (sync & async)

Send emails with a simple API, including:

• Plain text and HTML modes
• Attachments, CC/BCC, Reply-To
• Bulk and per-recipient sending
• Async sending via aiosmtplib
• XOAUTH2 authentication support

IMAP client with full mailbox control

Robust IMAP operations for automation:

• List and select mailboxes
• Search (UID-based), fetch, and fetch_many
• Parse headers, flags, plain text, HTML, attachments
• Mark seen, add/remove flags
• Move, delete, expunge
• Export tools: save attachments, dump JSON, save .eml

Security modes with explicit control

• auto — picks the safest option based on port and server capabilities
• starttls — explicit STARTTLS upgrade
• ssl — implicit SSL, typical for port 465
• none — plain mode for trusted internal networks
• allow_invalid_certs — for LAN/self-signed certificates

Templates and plain text fallback

Jinja2 templating with auto-escape ensures clean rendering. HTML emails automatically include a plain-text alternative for improved deliverability.

Environment variable configuration

Both EmailSender and ImapClient support zero-code configuration:

• EmailSender.from_env()
• ImapClient.from_env()

Ideal for Docker, CI/CD, and serverless environments.

Backward compatibility

Legacy SendAgent and ImapAgent remain available for older codebases while transitioning to the modern API.