mailworks 2.2.0

A Python package for sending emails using any SMTP server with STARTTLS support

MailWorks

A Python package for sending emails using any SMTP server with STARTTLS support. This package provides a simple, secure, and reliable way to send emails through any email provider including Gmail, Outlook, Yahoo, and more. Defaults to Gmail for convenience.

Features

• ✅ Universal SMTP Support - Works with any SMTP provider (Gmail, Outlook, Yahoo, ProtonMail, etc.)
• ✅ STARTTLS Security - Secure email transmission with TLS encryption
• ✅ Gmail Defaults - Pre-configured for Gmail, works out of the box
• ✅ Support for plain text and HTML emails
• ✅ File attachments
• ✅ Multiple recipients
• ✅ Environment variable configuration
• ✅ Configuration file support
• ✅ Connection testing
• ✅ Comprehensive error handling
• ✅ No external dependencies (uses Python standard library only)
• ✅ Backward compatibility (GmailSender alias available)

Installation

From source (development)

# Clone the repository
git clone https://github.com/antoniocostabr/mailworks.git
cd mailworks

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

From PyPI (when published)

pip install mailworks

Supported Email Providers

MailWorks supports any email provider that offers SMTP with STARTTLS encryption:

Provider	SMTP Server	Port	Notes
Gmail	smtp.gmail.com	587	Default configuration
Outlook/Hotmail	smtp-mail.outlook.com	587	Microsoft email services
Yahoo	smtp.mail.yahoo.com	587	Requires app password
ProtonMail	mail.protonmail.ch	587	Secure email provider
Zoho	smtp.zoho.com	587	Business email
SendGrid	smtp.sendgrid.net	587	Email delivery service
Amazon SES	email-smtp.region.amazonaws.com	587	AWS email service
Internal/Corporate	mail.company.com	25/587	No authentication required
Custom	your.smtp.server	587	Any SMTP server with STARTTLS

Gmail Setup (if using Gmail)

For Gmail users, you need to set up App Passwords:

Step 1: Enable 2-Factor Authentication

1. Go to Google Account settings
2. Navigate to "Security" > "2-Step Verification"
3. Enable 2-Step Verification if not already enabled

Step 2: Generate App Password

1. Go to Google Account settings
2. Navigate to "Security" > "2-Step Verification" > "App passwords"
3. Select "Mail" and your device
4. Generate the app password
5. Important: Use this 16-character app password, not your regular Gmail password

Quick Start

Basic Usage (Gmail - Default)

from mailworks import MailSender

# Using environment variables (Gmail defaults)
# Set environment variables:
# export EMAIL="[e-mail]"
# export PASSWORD="your_app_password"

sender = MailSender()

# Send a simple email
success = sender.send_simple_email(
    to_email="[e-mail]",
    subject="Hello from Python!",
    message="This is a test email sent from Python."
)

if success:
    print("Email sent successfully!")

Using Other Email Providers

from mailworks import MailSender

# Outlook/Hotmail
sender = MailSender(
    email="[e-mail]",
    password="your_password",
    smtp_server="smtp-mail.outlook.com",
    smtp_port=587
)

# Yahoo
sender = MailSender(
    email="[e-mail]",
    password="your_app_password",
    smtp_server="smtp.mail.yahoo.com",
    smtp_port=587
)

# Custom SMTP server
sender = MailSender(
    email="[e-mail]",
    password="your_password",
    smtp_server="mail.yourdomain.com",
    smtp_port=587
)

Internal/Corporate SMTP Servers (No Authentication)

For internal corporate SMTP servers that don't require authentication or TLS:

⚠️ Security Note: Authentication and TLS are enabled by default for security. Only disable them (auth_required=False, use_tls=False) for trusted internal SMTP servers within your corporate network.

from mailworks import MailSender

# Corporate SMTP server without authentication or TLS
sender = MailSender(
    email="[e-mail]",
    smtp_server="mail.company.com",
    smtp_port=25,  # Common for internal servers
    auth_required=False,  # Disable authentication
    use_tls=False  # Disable TLS for plain text internal servers
)

# Environment variables approach
# export EMAIL="[e-mail]"
# export SMTP_SERVER="mail.company.com"
# export SMTP_PORT="25"
# export AUTH_REQUIRED="false"
# export USE_TLS="false"
sender = MailSender()

# Send HTML email with attachments to multiple recipients
success = sender.send_email(
    to_emails=["[e-mail]", "[e-mail]"],
    subject="Advanced Email Example",
    message="Plain text version of the email.",
    html_message="""
    <html>
        <body>
            <h2>Hello!</h2>
            <p>This is an <b>HTML email</b> with formatting.</p>
        </body>
    </html>
    """,
    attachments=["document.pdf", "image.png"]
)

Configuration Options

1. Environment Variables (Recommended)

Set these environment variables:

# Required
export EMAIL="[e-mail]"
export PASSWORD="your_app_password"  # Not required if AUTH_REQUIRED=false

# Optional (defaults to Gmail if not specified)
export SMTP_SERVER="smtp.anyprovider.com"
export SMTP_PORT="587"
export AUTH_REQUIRED="true"  # Set to "false" for servers without authentication
export USE_TLS="true"  # Set to "false" for plain text internal servers

2. Configuration File

Create a config file (e.g., email_config.txt):

EMAIL=[e-mail]
PASSWORD=your_app_password
SMTP_SERVER=smtp.anyprovider.com
SMTP_PORT=587
AUTH_REQUIRED=true
USE_TLS=true

Use it in your code:

from mailworks.config import ConfigManager

config_manager = ConfigManager.from_file("email_config.txt")
sender = MailSender(
    email=config_manager.config.email,
    password=config_manager.config.password,
    smtp_server=config_manager.config.smtp_server,
    smtp_port=config_manager.config.smtp_port
)

3. Direct Parameters

from mailworks import MailSender

# Any SMTP provider
sender = MailSender(
    email="[e-mail]",
    password="your_password",
    smtp_server="smtp.anyprovider.com",
    smtp_port=587
)

# Gmail (using defaults)
sender = MailSender(
    email="[e-mail]",
    password="your_app_password"
)

API Reference

MailSender Class

Constructor

MailSender(email=None, password=None, smtp_server=None, smtp_port=None, auth_required=None, use_tls=None)

• email (str, optional): Email address. If not provided, reads from EMAIL environment variable.
• password (str, optional): Email password/app password. If not provided, reads from PASSWORD environment variable. Not required if auth_required=False.
• smtp_server (str, optional): SMTP server address. If not provided, reads from SMTP_SERVER environment variable or defaults to Gmail.
• smtp_port (int, optional): SMTP port number. If not provided, reads from SMTP_PORT environment variable or defaults to 587.
• auth_required (bool, optional): Whether SMTP authentication is required. Defaults to True for security. If not provided, reads from AUTH_REQUIRED environment variable or defaults to True. Set to False only for trusted internal SMTP servers.
• use_tls (bool, optional): Whether to use STARTTLS encryption. Defaults to True for security. If not provided, reads from USE_TLS environment variable or defaults to True. Set to False only for plain text internal SMTP servers that don't support TLS.

Methods

send_email(to_emails, subject, message, html_message=None, attachments=None)

Send an email with advanced options.

Parameters:

• to_emails (str or list): Recipient email address(es)
• subject (str): Email subject
• message (str): Plain text message body
• html_message (str, optional): HTML message body
• attachments (list, optional): List of file paths to attach

Returns: bool - True if successful

send_simple_email(to_email, subject, message)

Send a simple text email to a single recipient.

Parameters:

• to_email (str): Recipient email address
• subject (str): Email subject
• message (str): Plain text message body

Returns: bool - True if successful

test_connection()

Test the connection to the configured SMTP server.

Returns: bool - True if connection successful

GmailSender Class (Backward Compatibility)

For backward compatibility, GmailSender is available as an alias to MailSender:

from mailworks import GmailSender  # Same as MailSender

sender = GmailSender(email="[e-mail]", password="app_password")

Exception Classes

• EmailSenderError: Base exception class
• AuthenticationError: Raised when SMTP authentication fails
• SendError: Raised when email sending fails
• ConfigurationError: Raised when configuration is invalid

Examples

See the examples/ directory for complete working examples:

• basic_example.py: Simple email sending using environment variables
• advanced_example.py: HTML emails with attachments and multiple recipients
• smtp_providers_example.py: Examples for different email providers
• internal_smtp_example.py: Using internal/corporate SMTP servers without authentication
• config_example.py: Different configuration methods

Error Handling

from mailworks import MailSender, AuthenticationError, SendError

try:
    sender = MailSender()
    sender.test_connection()

    success = sender.send_simple_email(
        to_email="[e-mail]",
        subject="Test Email",
        message="Hello, World!"
    )

except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    print("Check your email and password")

except SendError as e:
    print(f"Failed to send email: {e}")

except Exception as e:
    print(f"Unexpected error: {e}")

Security Best Practices

1. Use App Passwords: Never use your regular Gmail password. Always use Gmail App Passwords.

2. Environment Variables: Store credentials in environment variables, not in your code.

3. Config Files: If using config files, add them to .gitignore to avoid committing credentials.

4. Permissions: Keep your app passwords secure and rotate them regularly.

Common Issues & Solutions

Authentication Error (535)

Problem: smtplib.SMTPAuthenticationError: (535, '5.7.8 Username and Password not accepted')

Solutions:

• Ensure you're using an App Password, not your regular Gmail password
• Check that 2-Factor Authentication is enabled on your Gmail account
• Verify the email address is correct
• Try generating a new App Password

Connection Issues

Problem: Connection timeouts or failures

Solutions:

• Check your internet connection
• Ensure port 587 is not blocked by your firewall
• Try using a different network
• Verify SMTP server settings for your provider

File Attachment Issues

Problem: Attachments not working

Solutions:

• Check that file paths exist and are accessible
• Ensure files are not too large (most providers have limits like 25MB for Gmail)
• Verify file permissions

Migration Guide

From v1.x (GmailSender only)

If you were using the old Gmail-only version:

# Old way (still works)
from mailworks import GmailSender
sender = GmailSender(email="[e-mail]", password="password")

# New recommended way
from mailworks import MailSender
sender = MailSender(email="[e-mail]", password="password")

Environment Variables

# Old variables (still supported for backward compatibility)
export GMAIL_EMAIL="[e-mail]"
export GMAIL_PASSWORD="your_app_password"

# New recommended variables
export EMAIL="[e-mail]"
export PASSWORD="your_app_password"
export SMTP_SERVER="smtp.anyprovider.com"  # Optional
export SMTP_PORT="587"                     # Optional

Development

Running Examples

# Set your credentials
export EMAIL="[e-mail]"
export PASSWORD="your_app_password"

# Run examples
python examples/basic_example.py
python examples/advanced_example.py
python examples/config_example.py

Testing

# Install development dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest

# Code formatting
black mailworks/
black examples/

# Type checking
mypy mailworks/

What's New in v2.0

🎉 Universal SMTP Support: No longer limited to Gmail! Now works with any email provider.

Key Improvements:

• ✅ Any SMTP Provider: Gmail, Outlook, Yahoo, ProtonMail, custom servers, etc.
• ✅ Clean Package Name: mailworks instead of email_sender
• ✅ Better Class Names: MailSender instead of GmailSender
• ✅ Simplified Configuration: Generic environment variables (EMAIL, PASSWORD)
• ✅ Backward Compatible: Existing code continues to work
• ✅ Enhanced Documentation: Comprehensive examples for all providers

Quick Comparison:

# v1.x - Gmail only
from email_sender import GmailSender
sender = GmailSender(email="[e-mail]", password="password")

# v2.x - Any provider
from mailworks import MailSender
sender = MailSender(
    email="[e-mail]",
    password="password",
    smtp_server="smtp-mail.outlook.com",
    smtp_port=587
)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed history of changes and version information.

Support

If you encounter any issues or have questions:

1. Check the Common Issues section
2. Look at the examples for usage patterns
3. Open an issue on GitHub

v1.0.0

• Initial release
• Gmail SMTP support
• HTML email support
• File attachments
• Multiple recipients
• Configuration management
• Comprehensive error handling