A flexible HTML email notification library for SMTP servers

These details have not been verified by PyPI

Project links

Project description

EmailSender

A flexible, lightweight Python library for sending HTML email notifications via SMTP. Perfect for sending notifications, alerts, and messages from your applications.

Features

📧 Send HTML-formatted emails with ease
🎨 Two operation modes:
- Wrap Mode: Automatically wrap messages with professional HTML styling
- Direct Mode: Send custom pre-formatted HTML content
⚙️ Configurable SMTP server (defaults to Gmail)
🔐 Support for app passwords and secure authentication
🔄 Backward compatible with legacy failure notification methods
✅ Comprehensive error handling

Installation

pip install email-sender-lib

Quick Start

Basic Usage (Wrap Mode)

from email_sender import EmailSender

# Initialize the email sender
sender = EmailSender(
    sender_email="your-email@gmail.com",
    sender_password="your-app-password",
    recipient_email="recipient@example.com"
)

# Send a simple notification
sender.send_notification(
    subject="Process Completed",
    message="Your task has been completed successfully!"
)

# Send with details
sender.send_notification(
    subject="Deployment Report",
    message="Application deployed successfully",
    details={
        "Version": "1.2.0",
        "Environment": "Production",
        "Duration": "2m 34s"
    }
)

Advanced Usage (Direct HTML Mode)

from email_sender import EmailSender

sender = EmailSender(
    sender_email="your-email@gmail.com",
    sender_password="your-app-password",
    recipient_email="recipient@example.com"
)

# Send with custom HTML
custom_html = """
<html>
<head>
    <style>
        body { font-family: Arial, sans-serif; }
        .header { background-color: #28a745; color: white; padding: 15px; }
    </style>
</head>
<body>
    <div class="header"><h2>Custom HTML Email</h2></div>
    <p>Your custom content here</p>
</body>
</html>
"""

sender.send_notification(
    subject="Custom Notification",
    html_content=custom_html
)

Using Custom SMTP Server

sender = EmailSender(
    sender_email="your-email@example.com",
    sender_password="your-password",
    recipient_email="recipient@example.com",
    smtp_server="smtp.outlook.com",  # Outlook/Office 365
    smtp_port=587
)

# Now you can send emails via any SMTP server
sender.send_notification(
    subject="Hello",
    message="Email via Outlook"
)

Send to Different Recipients

# Send to a specific recipient (overrides default)
sender.send_notification(
    subject="Important Update",
    message="This is for a specific recipient",
    recipient="other-user@example.com"
)

Configuration

Gmail Setup (Recommended)

To use Gmail with this library, you need to create an App Password:

Enable 2-Factor Authentication on your Google Account:
- Go to myaccount.google.com
- Click "Security" in the left sidebar
- Enable "2-Step Verification"
Create an App Password:
- Go to myaccount.google.com/apppasswords
- Select "Mail" and "Windows Computer" (or your device)
- Google will generate a 16-character password
- Copy this password and use it as sender_password in the library

Example with Gmail:

sender = EmailSender(
    sender_email="your-email@gmail.com",
    sender_password="xxxx xxxx xxxx xxxx",  # 16-char app password
    recipient_email="recipient@example.com"
)

Other SMTP Providers

Outlook/Office 365:

sender = EmailSender(
    sender_email="your-email@outlook.com",
    sender_password="your-password",
    recipient_email="recipient@example.com",
    smtp_server="smtp.office365.com",
    smtp_port=587
)

SendGrid:

sender = EmailSender(
    sender_email="apikey",  # Use 'apikey' as username
    sender_password="SG.xxxxx...",  # Your SendGrid API key
    recipient_email="recipient@example.com",
    smtp_server="smtp.sendgrid.net",
    smtp_port=587
)

Custom SMTP Server:

sender = EmailSender(
    sender_email="your-email@company.com",
    sender_password="your-password",
    recipient_email="recipient@example.com",
    smtp_server="mail.company.com",
    smtp_port=587
)

API Reference

EmailSender

`init(sender_email, sender_password, recipient_email, smtp_server="smtp.gmail.com", smtp_port=587)`

Initialize the email sender.

Parameters:

sender_email (str): Email address to send from
sender_password (str): Email password or app password
recipient_email (str): Default recipient email address
smtp_server (str, optional): SMTP server address (default: "smtp.gmail.com")
smtp_port (int, optional): SMTP port (default: 587)

Raises:

ValueError: If any required parameter is empty

`send_notification(subject, message=None, html_content=None, details=None, recipient=None)`

Send a notification email.

Parameters:

subject (str): Email subject line
message (str, optional): Main notification message (used in wrap mode)
html_content (str, optional): Pre-formatted HTML content (used in direct mode, takes precedence)
details (dict, optional): Dictionary with additional details (used in wrap mode)
recipient (str, optional): Recipient email (uses default if not provided)

Returns:

bool: True if email sent successfully, False otherwise

Modes:

Wrap Mode: Provide message and optional details for automatic HTML wrapping
Direct Mode: Provide html_content for custom HTML (takes precedence over message)

Examples:

# Wrap mode with details
sender.send_notification(
    subject="Alert",
    message="Something happened",
    details={"Status": "Critical", "Time": "12:34"}
)

# Direct mode with custom HTML
sender.send_notification(
    subject="Alert",
    html_content="<html>...</html>"
)

# Send to different recipient
sender.send_notification(
    subject="Alert",
    message="Hello",
    recipient="user@example.com"
)

`send_failure_notification(subject, message, details=None, recipient=None)` (Legacy)

Send a failure notification email. This method is deprecated but maintained for backward compatibility.

Parameters:

subject (str): Email subject line
message (str): Main failure message
details (dict, optional): Dictionary with failure details
recipient (str, optional): Recipient email (uses default if not provided)

Returns:

bool: True if email sent successfully, False otherwise

Error Handling

The library handles common SMTP errors gracefully:

from email_sender import EmailSender

sender = EmailSender(
    sender_email="your-email@gmail.com",
    sender_password="wrong-password",
    recipient_email="recipient@example.com"
)

# This will print error messages and return False
success = sender.send_notification(
    subject="Test",
    message="Test message"
)

if not success:
    print("Failed to send email")

Common errors:

Authentication failed: Check credentials and app password
Connection error: Verify SMTP server and port settings
Invalid email: Ensure email addresses are properly formatted

Use Cases

📢 Send application alerts and notifications
✅ Deploy confirmations and status updates
🔔 User notifications and reminders
📊 Report delivery and data summaries
⚠️ Error and failure notifications
📧 Newsletter and bulk email (with rate limiting)

Requirements

Python 3.7+
No external dependencies (uses only standard library)

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Note: Keep your app password secure. Never commit it to version control. Use environment variables instead:

import os
from email_sender import EmailSender

sender = EmailSender(
    sender_email=os.environ.get("EMAIL_ADDRESS"),
    sender_password=os.environ.get("EMAIL_PASSWORD"),
    recipient_email=os.environ.get("DEFAULT_RECIPIENT")
)

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

1.0.0

Nov 23, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

emaily-1.0.0.tar.gz (8.0 kB view details)

Uploaded Nov 23, 2025 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

emaily-1.0.0-py3-none-any.whl (10.1 kB view details)

Uploaded Nov 23, 2025 Python 3

File details

Details for the file emaily-1.0.0.tar.gz.

File metadata

Download URL: emaily-1.0.0.tar.gz
Upload date: Nov 23, 2025
Size: 8.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.0

File hashes

Hashes for emaily-1.0.0.tar.gz
Algorithm	Hash digest
SHA256	`2b8c56ed7f1d1fc5391ef89e1c4f755bfb489787437962ac3d26aeff268459fa`
MD5	`ec4e3bc7670e4688bdf73f75ad52f20f`
BLAKE2b-256	`376dbeb9b07abe84eb8b67038e5218d2e377288ba8c2c0a8aa8ff9590ba60ed6`

See more details on using hashes here.

File details

Details for the file emaily-1.0.0-py3-none-any.whl.

File metadata

Download URL: emaily-1.0.0-py3-none-any.whl
Upload date: Nov 23, 2025
Size: 10.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.0

File hashes

Hashes for emaily-1.0.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`3fae425552ed422718af0e50cecc052dbb8b8f2793debde55ce6e9e1e2d5200c`
MD5	`f76444b0e0e92776771d3255d3b8e540`
BLAKE2b-256	`4314e4ac5995f71dbeb4aff41f360ba514ed4fcb4b67884af14ed7ae24b981d2`

See more details on using hashes here.

Emaily 1.0.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

EmailSender

Features

Installation

Quick Start

Basic Usage (Wrap Mode)

Advanced Usage (Direct HTML Mode)

Using Custom SMTP Server

Send to Different Recipients

Configuration

Gmail Setup (Recommended)

Other SMTP Providers

API Reference

EmailSender

__init__(sender_email, sender_password, recipient_email, smtp_server="smtp.gmail.com", smtp_port=587)

send_notification(subject, message=None, html_content=None, details=None, recipient=None)

send_failure_notification(subject, message, details=None, recipient=None) (Legacy)

Error Handling

Use Cases

Requirements

License

Contributing

Support

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

`init(sender_email, sender_password, recipient_email, smtp_server="smtp.gmail.com", smtp_port=587)`

`send_notification(subject, message=None, html_content=None, details=None, recipient=None)`

`send_failure_notification(subject, message, details=None, recipient=None)` (Legacy)