Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Add documentation for email verification and password reset

Murtaza Nasirbcbf48724804
diff --git a/docs/admin-guide/email-setup.md b/docs/admin-guide/email-setup.md
new file mode 100644
index 00000000..975b4a37
--- /dev/null
+++ b/docs/admin-guide/email-setup.md
@@ -0,0 +1,225 @@
+# Email Verification & Password Reset
+
+This guide explains how to configure email functionality in Speakr, enabling email verification for new user registrations and password reset capabilities for all users.
+
+## Overview
+
+Email features in Speakr are completely opt-in. When configured, they provide:
+
+- **Email Verification**: Require new users to verify their email address before accessing the system
+- **Password Reset**: Allow users to reset forgotten passwords via email
+
+Both features work independently of domain restrictions—you can use email verification even with open registration (`ALLOW_REGISTRATION=true`) and no domain restrictions.
+
+## Prerequisites
+
+- SMTP server credentials (Gmail, SendGrid, Mailgun, Amazon SES, or any SMTP provider)
+- Speakr instance accessible via the URL you configure (for email links to work)
+
+## Configuration
+
+### Required Environment Variables
+
+Set these variables in your `.env` file (see `config/env.email.example` for a complete template):
+
+```bash
+# Enable email features
+ENABLE_EMAIL_VERIFICATION=true
+REQUIRE_EMAIL_VERIFICATION=false
+
+# SMTP Configuration
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_PASSWORD=your-app-password
+SMTP_USE_TLS=true
+SMTP_FROM_NAME=Speakr
+```
+
+Restart Speakr after updating environment variables.
+
+### Configuration Options
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ENABLE_EMAIL_VERIFICATION` | `false` | Enable email verification for new registrations |
+| `REQUIRE_EMAIL_VERIFICATION` | `false` | Block login for unverified users (only works when verification is enabled) |
+| `SMTP_HOST` | (none) | SMTP server hostname |
+| `SMTP_PORT` | `587` | SMTP server port |
+| `SMTP_USERNAME` | (none) | SMTP authentication username |
+| `SMTP_PASSWORD` | (none) | SMTP authentication password |
+| `SMTP_USE_TLS` | `true` | Use STARTTLS encryption (port 587) |
+| `SMTP_USE_SSL` | `false` | Use SSL encryption (port 465) |
+| `SMTP_FROM_ADDRESS` | `[email protected]` | Email address shown in "From" field |
+| `SMTP_FROM_NAME` | `Speakr` | Display name shown alongside from address |
+
+### Understanding the Two Verification Modes
+
+**Soft Verification** (`ENABLE_EMAIL_VERIFICATION=true`, `REQUIRE_EMAIL_VERIFICATION=false`):
+
+- New users receive a verification email after registration
+- Users can log in immediately without verifying
+- Useful for encouraging email verification without blocking access
+
+**Strict Verification** (`ENABLE_EMAIL_VERIFICATION=true`, `REQUIRE_EMAIL_VERIFICATION=true`):
+
+- New users receive a verification email after registration
+- Users cannot log in until they verify their email
+- Best for environments requiring confirmed email addresses
+
+### Combining with Other Registration Settings
+
+Email verification works seamlessly with other registration controls:
+
+```bash
+# Open registration with email verification
+ALLOW_REGISTRATION=true
+ENABLE_EMAIL_VERIFICATION=true
+REQUIRE_EMAIL_VERIFICATION=true
+
+# Domain-restricted registration with verification
+ALLOW_REGISTRATION=true
+REGISTRATION_ALLOWED_DOMAINS=company.com,subsidiary.org
+ENABLE_EMAIL_VERIFICATION=true
+REQUIRE_EMAIL_VERIFICATION=true
+
+# Closed registration (admin creates accounts)
+ALLOW_REGISTRATION=false
+# Email verification not applicable - admin creates verified accounts
+```
+
+## Provider-Specific Setup
+
+### Gmail
+
+```bash
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USE_TLS=true
+SMTP_PASSWORD=your-app-password
+```
+
+**Important:** Use an [App Password](https://support.google.com/accounts/answer/185833), not your regular Gmail password. App Passwords are required when 2-factor authentication is enabled (recommended).
+
+### SendGrid
+
+```bash
+SMTP_HOST=smtp.sendgrid.net
+SMTP_PORT=587
+SMTP_USE_TLS=true
+SMTP_USERNAME=apikey
+SMTP_PASSWORD=your-sendgrid-api-key
+```
+
+### Mailgun
+
+```bash
+SMTP_HOST=smtp.mailgun.org
+SMTP_PORT=587
+SMTP_USE_TLS=true
+SMTP_PASSWORD=your-mailgun-password
+```
+
+### Amazon SES
+
+```bash
+SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+SMTP_PORT=587
+SMTP_USE_TLS=true
+SMTP_USERNAME=your-ses-smtp-username
+SMTP_PASSWORD=your-ses-smtp-password
+```
+
+### Microsoft 365 / Outlook
+
+```bash
+SMTP_HOST=smtp.office365.com
+SMTP_PORT=587
+SMTP_USE_TLS=true
+SMTP_PASSWORD=your-password
+```
+
+### SSL vs TLS
+
+- **Port 587 with TLS** (recommended): Set `SMTP_USE_TLS=true`, `SMTP_USE_SSL=false`
+- **Port 465 with SSL**: Set `SMTP_USE_TLS=false`, `SMTP_USE_SSL=true`
+- **Port 25 (unencrypted)**: Not recommended for security reasons
+
+## User Experience
+
+### Registration Flow (with verification enabled)
+
+1. User fills out registration form
+2. Account is created with `email_verified=false`
+3. Verification email is sent automatically
+4. User sees "Check your email" page with option to resend
+5. User clicks verification link in email
+6. Account is marked as verified
+7. User can now log in (if `REQUIRE_EMAIL_VERIFICATION=true`)
+
+### Password Reset Flow
+
+1. User clicks "Forgot password?" on login page
+2. User enters their email address
+3. If account exists, reset email is sent (no indication if account doesn't exist for security)
+4. User clicks reset link in email
+5. User sets new password
+6. User is redirected to login
+
+### Token Expiry
+
+- **Email verification links**: Valid for 24 hours
+- **Password reset links**: Valid for 1 hour
+
+Users can request new links if their tokens expire.
+
+## Migration Behavior
+
+When enabling email verification on an existing instance:
+
+- **Existing users are automatically marked as verified** (grandfathered)
+- Only new registrations after enabling the feature require verification
+- No action needed for current users
+
+## Security Considerations
+
+1. **Use secure SMTP connections**: Always enable TLS or SSL
+2. **Use app-specific passwords**: When available (Gmail, etc.)
+3. **Set a strong SECRET_KEY**: Token security depends on your Flask secret key
+4. **Consider dedicated email services**: SendGrid, Mailgun, and SES offer better deliverability than personal email accounts
+
+## Troubleshooting
+
+### Emails not sending
+
+1. Check Docker logs: `docker compose logs -f app`
+2. Verify SMTP credentials are correct
+3. Ensure SMTP port is not blocked by firewall
+4. Try sending a test email using the same credentials from another tool
+
+### Emails going to spam
+
+1. Use a proper `SMTP_FROM_ADDRESS` that matches your domain
+2. Configure SPF and DKIM records for your domain
+3. Consider using a dedicated email service with good reputation
+
+### Verification link not working
+
+1. Ensure `SECRET_KEY` hasn't changed since the email was sent
+2. Check if the link has expired (24 hours for verification, 1 hour for reset)
+3. Verify your Speakr instance is accessible at the URL in the email
+
+### "SMTP not configured" errors
+
+Ensure all required SMTP variables are set:
+- `SMTP_HOST`
+- `SMTP_USERNAME`
+- `SMTP_PASSWORD`
+
+---
+
+Next: [SSO Setup](sso-setup.md) →
diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md
index 40aec35f..ca37d14b 100644
--- a/docs/admin-guide/index.md
+++ b/docs/admin-guide/index.md
@@ -60,6 +60,20 @@ Welcome to the Speakr Admin Guide! As an administrator, you control the heart of
<p>Configure automated data lifecycle management with flexible retention policies and smart deletion rules.</p>
<a href="retention" class="card-link">Manage Retention →</a>
</div>
+
+ <div class="guide-card">
+ <div class="card-icon">📧</div>
+ <h3>Email Setup</h3>
+ <p>Configure email verification for new registrations and enable password reset functionality.</p>
+ <a href="email-setup" class="card-link">Setup Email →</a>
+ </div>
+
+ <div class="guide-card">
+ <div class="card-icon">🔐</div>
+ <h3>SSO Setup</h3>
+ <p>Integrate with identity providers like Keycloak, Azure AD, Google, or Auth0 using OpenID Connect.</p>
+ <a href="sso-setup" class="card-link">Configure SSO →</a>
+ </div>
</div>
## Quick Actions
diff --git a/docs/features.md b/docs/features.md
index e69db325..bdccd6e6 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -189,6 +189,10 @@ Run a single Speakr instance for your entire group with isolated user spaces. Se
Integrate with your existing identity provider using OpenID Connect. Speakr supports any OIDC-compliant provider including Keycloak, Azure AD/Entra ID, Google, Auth0, and self-hosted options like Pocket ID or Authentik. Users can link existing accounts to SSO or have accounts created automatically on first login. Domain filtering lets you restrict registration to specific email domains. See the [SSO Setup Guide](admin-guide/sso-setup.md) for configuration details.
+### Email Verification & Password Reset
+
+Secure your instance with email verification for new registrations and enable self-service password recovery. When email verification is enabled, new users must confirm their email address before gaining access—works with both open registration and domain-restricted setups. Users can reset forgotten passwords through a secure, time-limited email link from the login page. Configure any SMTP provider including Gmail, SendGrid, Mailgun, or Amazon SES. Existing users are automatically grandfathered as verified when enabling this feature. See the [Email Setup Guide](admin-guide/email-setup.md) for configuration details.
+
### System Monitoring
Track system health with comprehensive statistics and metrics. Monitor transcription queues, storage usage, and processing performance. Identify bottlenecks and optimize configuration based on actual usage patterns.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index a633809b..2a63b9b1 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -206,6 +206,27 @@ REGISTRATION_ALLOWED_DOMAINS=company.com,subsidiary.org
Leave empty to allow all domains.
+### Enable Email Verification & Password Reset
+
+Speakr supports email verification for new registrations and password reset functionality. This works with both open registration and domain-restricted registration. Configure SMTP settings to enable:
+
+```bash
+# Enable email features
+ENABLE_EMAIL_VERIFICATION=true
+REQUIRE_EMAIL_VERIFICATION=true # Block login until email is verified
+
+# SMTP Configuration
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_PASSWORD=your-app-password # Use App Password for Gmail
+SMTP_USE_TLS=true
+SMTP_FROM_NAME=Speakr
+```
+
+When enabled, new users receive a verification email after registration. Password reset is available from the login page via "Forgot password?" link. See the [Email Setup Guide](admin-guide/email-setup.md) for detailed configuration including provider-specific examples for Gmail, SendGrid, Mailgun, and more.
+
### Configure Your Timezone
Set your local timezone for accurate timestamp display: