Tzylo Docs

SMTP & Email OTP

Configure SMTP to enable email-based OTP authentication flows.

Tzylo Auth CE supports known-user email OTP flows using SMTP. These flows are optional and enabled only when SMTP is configured.

When SMTP is required

SMTP configuration is required for the following features:

  • Email OTP login
  • Account verification via OTP
  • Forgot password and password reset
If SMTP is not configured, email-based OTP routes will not function.

Supported OTP flows

  • Send OTP to registered email
  • Verify OTP for authentication
  • Send OTP for password reset

SMTP configuration

Configure SMTP using the following environment variables:

SMTP environment variables
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@example.com
SMTP_PASSWORD=your-16-char-email-app-password

These values are read at startup. Restart the server after making changes.

Gmail example

When using Gmail, use an App Password instead of your account password.

Gmail SMTP
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=yourname@gmail.com
SMTP_PASSWORD=app-password
Do not hardcode SMTP credentials in source code or commit them to version control.

Email content

OTP emails include:

  • Application name
  • One-time password
  • Expiration information

Email templates are intentionally simple and focused on clarity.

Development notes

  • Use a test SMTP account for development
  • Verify spam folders when testing
  • Ensure outbound SMTP traffic is allowed in your environment

Common failure cases

  • Invalid SMTP credentials
  • Incorrect host or port
  • Blocked outbound email by hosting provider
  • Email provider rate limits

SMTP-related errors are logged during request handling.