Skip to content

SMTP Integration

userharbor-smtp provides SMTPEmailSender, an EmailSender implementation that sends verification, password-reset, and account security notification messages through SMTP.

Repository:

https://github.com/userharbor/userharbor-smtp

Installation

pip install userharbor-smtp

You can also install it through the core package extra:

pip install "userharbor[smtp]"

Basic 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",
)

Pass the sender to UserHarbor as its email_sender. UserHarbor calls it when it needs to send:

  • email verification messages
  • password reset messages
  • email-verified notifications
  • password-changed notifications
  • account-deleted notifications

Configuration

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",
    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,
)

Use use_starttls=True for the common SMTP submission flow on port 587. Use use_ssl=True for implicit TLS, commonly on port 465. When use_ssl=True, STARTTLS is not started separately.

The sender uses Python's secure default SSL context, which verifies the SMTP server certificate and hostname. 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. Set allow_insecure=True only for a trusted local SMTP relay where plaintext transport is an explicit, deliberate choice.

If both username and password are provided, the sender authenticates before sending the message.

Templates

By default, the package uses bundled HTML templates:

  • verification.html
  • password_reset.html
  • email_verified.html
  • password_changed.html
  • account_deleted.html

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

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

Verification and password reset templates also receive token.

Example templates/emails/verification.html:

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

Example templates/emails/password_reset.html:

<p>Hello {{ username }},</p>
<p>Use this token to reset your password:</p>
<p><strong>{{ token }}</strong></p>

Example templates/emails/password_changed.html:

<p>Hello {{ username }},</p>
<p>The password for {{ email }} was changed.</p>