A secure and enterprise-grade email sender library for any workflow, including AI applications
Project description
Mail Sender
A secure and enterprise-grade email sender library for any workflow, including AI applications.
📋 Overview
Mail Sender is a Python library that provides a simple yet powerful interface for sending emails securely. It's designed to be integrated into any workflow, with special consideration for AI applications.
✨ Features
- 🔒 Security-First Design: Built with security as a top priority
- 📝 Flexible Content Support: Send plain text or HTML emails
- 📎 File Attachments: Easily attach files to your emails
- 📨 Bulk Email Support: Send to multiple recipients with customizable time intervals
- 🧩 Zero External Dependencies: Only requires aiosmtplib and jinja2 beyond the Python standard library
- 🤖 AI Ready: Seamlessly integrates with AI workflows
🚀 Enterprise Features
- ⚡ Async Support: Send emails asynchronously for non-blocking operation
- 📊 Comprehensive Logging: Detailed logging for monitoring and debugging
- 🔄 Automatic Retry: Built-in retry mechanism for handling transient errors
- ⏱️ Rate Limiting: Control email sending rates to comply with provider limits
- 📄 Template System: Jinja2 templates for beautiful, consistent email content
- 🔌 Connection Pooling: Reuse connections for better performance in high-volume scenarios
📦 Installation
pip install ai-agent-mail-sender
🚀 Quick Start
from mail_sender import EmailSender
# Initialize the email sender
sender = EmailSender(
host="smtp.example.com", # SMTP server host
port=587, # SMTP server port
username="your_email@example.com",
password="your_password",
use_tls=True # Default is True
)
# Send a simple email
success = sender.send_email(
to_emails="recipient@example.com",
subject="Hello from Mail Sender",
content="This is a test email sent using the Mail Sender library.",
is_html=False # Default is False
)
if success:
print("Email sent successfully!")
else:
print("Failed to send email.")
# Send an HTML email with an attachment
html_content = """
<html>
<body>
<h1>Hello from Mail Sender</h1>
<p>This is an <b>HTML</b> email sent using the Mail Sender library.</p>
<p>This email includes a PDF attachment.</p>
</body>
</html>
"""
sender.send_email(
to_emails="recipient@example.com",
subject="HTML Email with Attachment",
content=html_content,
attachments=["path/to/document.pdf"],
is_html=True
)
# Send to multiple recipients with time intervals between emails
recipients = ["recipient1@example.com", "recipient2@example.com", "recipient3@example.com"]
results = sender.send_bulk_email(
to_emails=recipients,
subject="Bulk Email Test",
content="This is a test email sent to multiple recipients.",
attachments=["path/to/document.pdf"], # Optional
is_html=False,
individual_emails=True, # Send separate emails to each recipient
interval=1.5, # 1.5 minutes between emails
randomize_interval=True # Randomize the interval between 0 and 1.5 minutes
)
# Check results
for email, success in results.items():
print(f"{email}: {'Success' if success else 'Failed'}")
🔍 Enterprise Examples
Check out the examples directory for detailed usage examples:
- Basic Example: Simple text and HTML emails
- Advanced Example: Attachments and bulk emailing with intervals
- AI Workflow Example: Integration with AI-generated content
- Enterprise Example: Demonstrates async, logging, retry, rate limiting, templates, and connection pooling
Async Email Sending
import asyncio
from mail_sender import EmailSender
async def send_emails():
sender = EmailSender(
host="smtp.example.com",
port=587,
username="your_email@example.com",
password="your_password",
use_tls=True,
pool_connections=True # Enable connection pooling
)
# Send an email asynchronously
success = await sender.send_email_async(
to_emails="recipient@example.com",
subject="Async Email Example",
content="This is an asynchronous email.",
is_html=False
)
# Send bulk emails asynchronously with concurrency control
results = await sender.send_bulk_email_async(
to_emails=["recipient1@example.com", "recipient2@example.com"],
subject="Async Bulk Email",
content="This is a bulk async email.",
individual_emails=True,
concurrency_limit=5 # Limit concurrent sends
)
# Run the async function
asyncio.run(send_emails())
Template-Based Emails
from mail_sender import EmailSender
sender = EmailSender(
host="smtp.example.com",
port=587,
username="your_email@example.com",
password="your_password"
)
# Send email using a template
sender.send_email(
to_emails="recipient@example.com",
subject="Template Email Example",
content="", # Content will come from the template
template_name="basic_template.html",
template_context={
"subject": "Welcome to Our Service",
"content": "<p>Thank you for signing up!</p>",
"action_url": "https://example.com/dashboard",
"action_text": "Go to Dashboard",
"company_name": "Your Company"
}
)
📚 API Reference
EmailSender
EmailSender(
host,
port,
username,
password,
use_tls=True,
log_level=logging.INFO,
max_retries=3,
retry_delay=1.0,
rate_limit=None,
pool_connections=False,
pool_size=5
)
Parameters
host(str): SMTP server host (e.g., smtp.gmail.com)port(int): SMTP server port (e.g., 587 for TLS, 465 for SSL)username(str): Email account username/email addresspassword(str): Email account password or app passworduse_tls(bool, optional): Whether to use TLS encryption. Default is True.log_level(int, optional): Logging level from the logging module. Default is INFO.max_retries(int, optional): Maximum number of retry attempts for failed emails. Default is 3.retry_delay(float, optional): Delay between retry attempts in seconds. Default is 1.0.rate_limit(int, optional): Maximum number of emails per minute. Default is None (no limit).pool_connections(bool, optional): Whether to use connection pooling. Default is False.pool_size(int, optional): Maximum number of connections to keep in the pool. Default is 5.
send_email
send_email(
to_emails,
subject,
content,
attachments=None,
is_html=False,
template_name=None,
template_context=None
)
Parameters
to_emails(str or list): A single email address or a list of email addressessubject(str): Email subjectcontent(str): Email content (plain text or HTML)attachments(list, optional): List of file paths to attach to the emailis_html(bool, optional): Whether the content is HTML. Default is False.template_name(str, optional): Name of template file to use instead of content. Default is None.template_context(dict, optional): Context data for template rendering. Default is None.
Returns
bool: True if email was sent successfully, False otherwise
send_email_async
async send_email_async(
to_emails,
subject,
content,
attachments=None,
is_html=False,
template_name=None,
template_context=None
)
Asynchronous version of send_email with the same parameters and return value.
send_bulk_email
send_bulk_email(
to_emails,
subject,
content,
attachments=None,
is_html=False,
individual_emails=False,
interval=None,
randomize_interval=False,
template_name=None,
template_context=None
)
Parameters
to_emails(list): List of email addressessubject(str): Email subjectcontent(str): Email content (plain text or HTML)attachments(list, optional): List of file paths to attach to the emailis_html(bool, optional): Whether the content is HTML. Default is False.individual_emails(bool, optional): Whether to send individual emails to each recipient. Default is False.interval(float, optional): Time interval in minutes between emails (0-5 min). Default is None (no interval).randomize_interval(bool, optional): Whether to randomize the interval within the specified range. Default is False.template_name(str, optional): Name of template file to use instead of content. Default is None.template_context(dict, optional): Context data for template rendering. Default is None.
Returns
dict: Results of the email sending with email addresses as keys and success status as values
send_bulk_email_async
async send_bulk_email_async(
to_emails,
subject,
content,
attachments=None,
is_html=False,
individual_emails=False,
concurrency_limit=5,
template_name=None,
template_context=None
)
Parameters
Same as send_bulk_email, with the addition of:
concurrency_limit(int, optional): Maximum number of concurrent email sends. Default is 5.
Returns
dict: Results of the email sending with email addresses as keys and success status as values
render_template
render_template(template_name, **context)
Parameters
template_name(str): Name of the template file**context: Variables to pass to the template
Returns
str: Rendered template content
🔐 Security Features
- Secure connections with TLS/SSL by default
- Protected password handling
- Secure file attachment processing
- SSL context with default security settings
- Automatic cleanup of sensitive information
📧 Common SMTP Server Settings
Gmail
- Host:
smtp.gmail.com - Port:
587(TLS) or465(SSL) - Username: Your Gmail address
- Password: App password (if 2FA is enabled)
- Go to your Google Account Security settings
- Enable 2-Step Verification if not already enabled
- Go to "App passwords" and generate a new password for your app
- Use this 16-character password in the library
Outlook/Hotmail
- Host:
smtp.office365.com - Port:
587 - Username: Your Outlook email address
- Password: Your password
Yahoo Mail
- Host:
smtp.mail.yahoo.com - Port:
587(TLS) or465(SSL) - Username: Your Yahoo email address
- Password: App password (if 2FA is enabled)
GoDaddy
- Host:
smtpout.secureserver.net - Port:
465(SSL) or587(TLS) - Username: Your full email address
- Password: Your email password
🏢 Enterprise Use Cases
- Customer Communication: Send personalized emails to customers
- Reporting Systems: Automatically email reports to stakeholders
- AI Applications: Send AI-generated insights and recommendations
- Alert Systems: Send critical alerts and notifications
- Marketing Campaigns: Manage email marketing campaigns with interval controls
- High-Volume Applications: Handle thousands of emails with connection pooling and rate limiting
- Mission-Critical Systems: Ensure delivery with retry mechanisms and detailed logging
👥 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
👨💻 Author
MD ZAID ANWAR
Email: zaidanwar26@gmail.com
GitHub: Brainstorm2605
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ai_agent_mail_sender-0.2.2.tar.gz.
File metadata
- Download URL: ai_agent_mail_sender-0.2.2.tar.gz
- Upload date:
- Size: 16.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fbc0ea4542782cd73b1b2aa3032bdab85bd18390abf00cb0219f620edf946ad6
|
|
| MD5 |
21a244b417129af117e3c821e3ee497c
|
|
| BLAKE2b-256 |
9cc711580411a9c10eaaab0ebb0fda00606df766780a499af11dc9b2822d412f
|
File details
Details for the file ai_agent_mail_sender-0.2.2-py3-none-any.whl.
File metadata
- Download URL: ai_agent_mail_sender-0.2.2-py3-none-any.whl
- Upload date:
- Size: 20.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8e76ee0999f109ebf939113a844e6c04356295ec3961e0f3872443d188f1dced
|
|
| MD5 |
ee2d8d3c0671a6bd0582489fd8faeac8
|
|
| BLAKE2b-256 |
802bf53cfff8defb05c3f45bcb58b4cf64a4971639c8349f3467c5248a60c428
|
