email-sender

Reusable email sender for Python applications using Jinja2 HTML templates.

Works with FastAPI, Flask, Django, or any plain Python project.

Features

• Send emails with HTML templates using Jinja2.
• Async and sync sending.
• FastAPI BackgroundTasks helper.
• Support for CC, BCC, and attachments.
• Configurable via environment variables or explicit settings.

Installation

pip install email-sender

For FastAPI integration:

pip install email-sender[fastapi]

Configuration

Set the following environment variables:

MAIL_USERNAME=your_email@example.com
MAIL_PASSWORD=your_password_or_app_password
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_FROM_ADDRESS=your_email@example.com
MAIL_STARTTLS=True
MAIL_SSL_TLS=False

Or create an EmailSettings instance manually:

from email_sender import EmailSettings

settings = EmailSettings(
    username="your_email@example.com",
    password="your_password",
    server="smtp.gmail.com",
    port=587,
    from_address="your_email@example.com",
)

Usage

FastAPI with BackgroundTasks (recommended)

from fastapi import FastAPI, BackgroundTasks
from email_sender import send_email_background

app = FastAPI()

@app.post("/register")
async def register(background_tasks: BackgroundTasks, email: str, name: str):
    send_email_background(
        background_tasks,
        to=[email],
        subject="Welcome",
        template_name="welcome.html",
        context={"name": name, "app_name": "MyApp"},
    )
    return {"message": "User registered"}

Async usage

from email_sender import send_email

await send_email(
    to=["user@example.com"],
    subject="Verify your email",
    template_name="verify_email.html",
    context={"name": "John", "verification_url": "https://example.com/verify?token=abc"},
)

Sync usage (outside event loop)

from email_sender import send_email_sync

send_email_sync(
    to=["user@example.com"],
    subject="Welcome",
    template_name="welcome.html",
    context={"name": "John", "app_name": "MyApp"},
)

Custom templates

You can point to your own templates folder:

settings = EmailSettings(
    template_dir="/path/to/your/templates",
    # ... other config
)

await send_email(
    to=["user@example.com"],
    subject="Hello",
    template_name="custom.html",
    context={"name": "John"},
    settings=settings,
)

Your custom templates should extend base.html or be standalone HTML files.

Included templates

• welcome.html
• verify_email.html
• otp.html
• password_changed.html

Development

git clone https://github.com/yourusername/email-sender.git
cd email-sender
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Running tests

pytest

License

MIT