Metadata-Version: 2.4
Name: async-email-sender
Version: 0.1.0
Summary: Reusable email sender for Python applications using Jinja2 templates.
Author-email: Cristian Escobar <caes1996@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/email-sender
Project-URL: Repository, https://github.com/yourusername/email-sender
Project-URL: Issues, https://github.com/yourusername/email-sender/issues
Keywords: email,smtp,jinja2,fastapi-mail,templates
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi-mail>=1.4.0
Requires-Dist: Jinja2>=3.1.0
Requires-Dist: pydantic-settings>=2.0.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# email-sender

[![Tests](https://github.com/yourusername/email-sender/actions/workflows/tests.yml/badge.svg)](https://github.com/yourusername/email-sender/actions/workflows/tests.yml)
[![PyPI version](https://badge.fury.io/py/email-sender.svg)](https://badge.fury.io/py/email-sender)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install email-sender
```

For FastAPI integration:

```bash
pip install email-sender[fastapi]
```

## Configuration

Set the following environment variables:

```bash
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:

```python
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)

```python
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

```python
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)

```python
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:

```python
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

```bash
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

```bash
pytest
```

## License

MIT
