SMTP email sender integration for userharbor.

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

Installation

pip install userharbor-smtp

Usage

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
• email_verified.html
• password_changed.html
• account_deleted.html

To use custom templates, pass a pathlib.Path to a directory containing files with the same names:

from pathlib import Path

email_sender = SMTPEmailSender(
    host="smtp.example.com",
    port=587,
    username="smtp-user",
    password="smtp-password",
    from_email="noreply@example.com",
    template_dir=Path("templates/emails"),
    template_context={"app_url": "https://example.com"},
)

Each template receives:

• username
• email
• token for verification and password reset messages

Use template_context to add variables to every template. Built-in variables username, email, and token take precedence over custom values.

Example templates/emails/verification.html:

<p>Hello {{ username }},</p>
<p><a href="{{ app_url }}/auth/verify_email?token={{ token | urlencode }}">Verify {{ email }}</a></p>

Configuration

SMTPEmailSender(
    host="smtp.example.com",
    from_email="noreply@example.com",
    port=587,
    username=None,
    password=None,
    from_name=None,
    template_dir=None,
    template_context=None,
    verification_subject="Verify your email",
    password_reset_subject="Reset your password",
    email_verified_subject="Email verified",
    password_changed_subject="Password changed",
    account_deleted_subject="Account deleted",
    use_starttls=True,
    use_ssl=False,
    ssl_context=None,
    allow_insecure=False,
    timeout=10,
)

TLS certificate and hostname verification use Python's secure default SSL context. Pass ssl_context only when the application needs a custom trusted certificate authority or TLS policy. At least one of use_starttls and use_ssl must be enabled by default. Set allow_insecure=True only for a trusted local SMTP relay where plaintext transport is an explicit decision.

License

UserHarbor SMTP is released under the MIT License.