Metadata-Version: 2.4
Name: userharbor-smtp
Version: 0.1.0
Summary: SMTP integration for UserHarbor, a framework agnostic user management system for Python applications.
Keywords: auth,authentication,authorization,login,registration,security,sessions,signup,user-management,users
Author: SpaceShaman
Author-email: SpaceShaman <spaceshaman@tuta.io>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: jinja2>=3.0.0
Requires-Dist: userharbor>=0.1.1
Requires-Python: >=3.10
Project-URL: Documentation, https://userharbor.github.io/userharbor
Project-URL: Homepage, https://github.com/userharbor/userharbor-smtp
Project-URL: Repository, https://github.com/userharbor/userharbor-smtp
Description-Content-Type: text/markdown

<picture>
  <img src="https://github.com/userharbor/userharbor/raw/master/docs/assets/logo-full.png" alt="userharbor">
</picture>

[![GitHub License](https://img.shields.io/github/license/userharbor/userharbor-smtp)](https://github.com/userharbor/userharbor-smtp?tab=MIT-1-ov-file)
[![Tests](https://img.shields.io/github/actions/workflow/status/userharbor/userharbor-smtp/publish.yml?label=tests)](https://github.com/userharbor/userharbor-smtp/blob/master/.github/workflows/tests.yml)
[![Codecov](https://img.shields.io/codecov/c/github/userharbor/userharbor-smtp)](https://codecov.io/gh/userharbor/userharbor-smtp)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/userharbor-smtp)](https://pypi.org/project/userharbor-smtp)
[![PyPI - Version](https://img.shields.io/pypi/v/userharbor-smtp)](https://pypi.org/project/userharbor-smtp)
[![Code style: black](https://img.shields.io/badge/code%20style-black-black)](https://github.com/psf/black)
[![Linting: Ruff](https://img.shields.io/badge/linting-Ruff-black?logo=ruff&logoColor=black)](https://github.com/astral-sh/ruff)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Pytest](https://img.shields.io/badge/testing-Pytest-red?logo=pytest&logoColor=red)](https://docs.pytest.org/)
[![Zensical](https://img.shields.io/badge/docs-Zensical-yellow?logo=MaterialForMkDocs&logoColor=yellow)](https://userharborpaceshaman.github.io/userharbor/)

> **Project status:** UserHarbor SQLAlchemy is currently in an early stage of development.
> The API may change frequently. The library is not ready for production use yet.
# userharbor-smtp

SMTP email sender integration for
[`userharbor`](https://github.com/userharbor/userharbor).

The package provides `SMTPEmailSender`, an implementation of UserHarbor's
`EmailSender` protocol. It sends verification and password reset messages with
Python's standard `smtplib` and renders HTML email templates with Jinja.

## Installation

```bash
pip install userharbor-smtp
```

## Usage

```python
from userharbor_smtp import SMTPEmailSender

email_sender = SMTPEmailSender(
    host="smtp.example.com",
    port=587,
    username="smtp-user",
    password="smtp-password",
    from_email="noreply@example.com",
    from_name="UserHarbor",
)
```

By default, the sender uses HTML templates bundled with the package:

* `verification.html`
* `password_reset.html`

To use custom templates, pass a directory containing files with the same names:

```python
email_sender = SMTPEmailSender(
    host="smtp.example.com",
    port=587,
    username="smtp-user",
    password="smtp-password",
    from_email="noreply@example.com",
    template_dir="templates/emails",
)
```

Each template receives:

* `username`
* `email`
* `token`

Example `templates/emails/verification.html`:

```html
<p>Hello {{ username }},</p>
<p>Use this token to verify {{ email }}:</p>
<p><strong>{{ token }}</strong></p>
```

## Configuration

```python
SMTPEmailSender(
    host="smtp.example.com",
    from_email="noreply@example.com",
    port=587,
    username=None,
    password=None,
    from_name=None,
    template_dir=None,
    verification_subject="Verify your email",
    password_reset_subject="Reset your password",
    use_starttls=True,
    use_ssl=False,
    timeout=10,
)
```

## License

UserHarbor SMTP is released under the MIT License.
