Email SMTP

Email / SMTP

Email OTP is an optional backup factor: a user who loses their authenticator can receive a single-use code by email (expires in 5 minutes). It requires SMTP credentials in Settings → SMTP.

---

Gmail (with an app password)

SMTP Host:     smtp.gmail.com
SMTP Port:     587
Use SSL/TLS:   ✓
SMTP Username: your-email@gmail.com
SMTP Password: <generate at https://myaccount.google.com/apppasswords>
From Address:  your-email@gmail.com
From Name:     Jellyfin 2FA

Gmail requires an app password (not your account password), which means 2FA must be enabled on the Google account first. Regular-password SMTP login is blocked by Google.

---

Generic SMTP relay

SMTP Host:   mail.example.com
SMTP Port:   587 (STARTTLS)  or  465 (implicit TLS)
Use SSL/TLS: ✓

Port 465 uses implicit TLS (the socket is encrypted from the start); port 587 uses STARTTLS (upgrades a plaintext connection). The plugin maps the SSL/TLS option to the right socket behavior per port.

---

Per-user email addresses

Email OTP needs each user's email address. In Admin → Users, edit the email field per user.

The plugin does not auto-pull email from Jellyfin user metadata — Jellyfin's User entity exposes email inconsistently across versions, so admins enter it explicitly. Alternatively, each user can set their own email on the Setup page (/TwoFactorAuth/Setup).

---

Testing

Settings → SMTP has a Test SMTP button. On failure, the full error goes to the server log (the UI shows a generic message so SMTP details aren't leaked to the browser) — check the Jellyfin log if the test fails.

---

What email OTP is used for

• A backup factor at the 2FA challenge page (alongside authenticator + recovery code).
• An emailed 8-digit step-up code for hardened self-service factor changes when a user has email but no TOTP/passkey.
• Delivering codes during account recovery.

---

Password recovery by email (#71, v2.5.11)

A self-service "Forgot password?" flow. When enabled (and SMTP is configured), the login page shows a Forgot password? link; the user enters their username or email and is sent a one-time link to set a new password.

Enable: Settings → Security → Allow password recovery by email. Requires SMTP (above) and an email on file for the user (Users tab, or auto-filled from their IdP — see OIDC / SSO).

(v2.5.12) Hide Jellyfin's built-in link: a sub-option under the setting — "Hide Jellyfin's built-in Forgot password? link on the login page" (default on) — removes Jellyfin's native recovery link so users see only the plugin's flow. Uncheck it to keep both.

How it's kept safe:

• The reset token is single-use, expires in 30 minutes, and is stored only as a hash.
• Requests are rate-limited per source IP and per identifier.
• The response is always generic ("if an account exists, a link was sent"), so it can't be used to discover which accounts or emails exist.
• The link won't appear at all unless recovery is enabled and SMTP is set.

User flow: Forgot password? → enter username/email → open the emailed link → choose a new password → sign in. Re-using a spent link shows "invalid or expired".