Skip to main content
ClassQuiz uses SMTP to send email verification links and password reset emails to users. This guide covers how to configure email settings.

​
Email Settings

All email configuration is done through environment variables. These settings are required unless you disable email verification.
​
MAIL_SERVER
string
required
SMTP server hostname.Examples:
  • Gmail: smtp.gmail.com
  • Outlook: smtp.office365.com
  • SendGrid: smtp.sendgrid.net
  • Mailgun: smtp.mailgun.org
Example: smtp.gmail.com
​
MAIL_PORT
integer
required
SMTP server port. Common ports:
  • 587 - STARTTLS (recommended)
  • 465 - SSL/TLS
  • 25 - Plain (not recommended)
Default: 587
​
MAIL_USERNAME
string
required
Username for SMTP authentication. Usually your email address.Example: [email protected]
​
MAIL_PASSWORD
string
required
Password for SMTP authentication.
For Gmail, you must use an App Password, not your regular account password.
Example: your-app-password
​
MAIL_ADDRESS
string
required
Email address to use in the “From” field of sent emails.Example: [email protected]

​
Email Verification Control

​
SKIP_EMAIL_VERIFICATION
boolean
default:"false"
Whether to skip email verification for new user registrations.When set to True:
  • Users can log in immediately after registration
  • No verification emails are sent
  • Email fields are still validated but not verified
When set to False:
  • Users must click a verification link sent to their email
  • Users cannot log in until their email is verified
Values: True or False
During development or testing, you may want to set SKIP_EMAIL_VERIFICATION=True to avoid needing a working SMTP server.

​
Configuration Examples

MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-app-password
MAIL_ADDRESS=[email protected]
SKIP_EMAIL_VERIFICATION=False

​
Email Templates

ClassQuiz sends two types of emails:

​
Registration Verification Email

Sent when a new user registers. Contains a verification link that expires based on your token settings. Template location: classquiz/emails/templates/register.jinja2 Variables available:
  • base_url - Your ROOT_ADDRESS
  • token - Verification token

​
Password Reset Email

Sent when a user requests a password reset. The reset link expires after 1 hour (3600 seconds). Template location: classquiz/emails/templates/forgotten_password.jinja2 Variables available:
  • base_url - Your ROOT_ADDRESS
  • token - Password reset token
Email templates use Jinja2 templating. You can customize these templates by modifying the files in the classquiz/emails/templates/ directory.

​
Provider-Specific Setup

1

Enable 2-Factor Authentication

You must enable 2FA on your Google account to use App Passwords.
2

Generate App Password

  1. Go to Google Account Settings
  2. Navigate to Security → 2-Step Verification → App passwords
  3. Select “Mail” and “Other (Custom name)”
  4. Copy the 16-character password
3

Configure ClassQuiz

MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=xxxx-xxxx-xxxx-xxxx  # App password
MAIL_ADDRESS=[email protected]
1

Create API Key

  1. Log in to SendGrid
  2. Go to Settings → API Keys
  3. Create a new API key with “Mail Send” permissions
2

Verify Domain (Optional)

For production, verify your domain in SendGrid to improve deliverability.
3

Configure ClassQuiz

MAIL_SERVER=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey  # Literally the word "apikey"
MAIL_PASSWORD=SG.xxxxx  # Your actual API key
MAIL_ADDRESS=[email protected]
For self-hosted or custom SMTP servers:
  1. Ensure your SMTP server supports STARTTLS on port 587
  2. Create a dedicated email account for ClassQuiz
  3. Configure firewall rules to allow outbound connections on port 587
  4. Test with:
openssl s_client -starttls smtp -connect smtp.yourserver.com:587

​
Testing Email Configuration

After configuring email settings, test the configuration by:
1

Register a test user

Create a new account with a real email address you can access.
2

Check email delivery

Verify that you receive the verification email within a few minutes.
3

Check spam folder

If emails aren’t arriving, check your spam/junk folder.
4

Review logs

Check ClassQuiz logs for SMTP errors:
docker-compose logs api | grep -i mail

​
Troubleshooting

Check that:
  • All MAIL_* environment variables are set correctly
  • SKIP_EMAIL_VERIFICATION is set to False
  • Your SMTP server is reachable from the ClassQuiz container
  • Firewall rules allow outbound connections on your MAIL_PORT
View logs:
docker-compose logs api
Common causes:
  • Gmail: Using account password instead of App Password
  • Office 365: Account has 2FA enabled without app-specific password
  • Incorrect username or password
  • Account locked due to suspicious activity
Test SMTP authentication:
python3 -m smtplib -d smtp.gmail.com:587
To improve email deliverability:
  • Set up SPF, DKIM, and DMARC records for your domain
  • Use a verified domain email address
  • Use a reputable SMTP provider (SendGrid, Mailgun, etc.)
  • Avoid generic words like “noreply” in the email address
ClassQuiz uses STARTTLS with SSL protocol TLS. If you encounter SSL errors:
  • Ensure you’re using port 587 (not 465 or 25)
  • Check if your SMTP server supports STARTTLS
  • Verify SSL certificates are valid
The SMTP connection uses ssl.PROTOCOL_TLS with starttls().

​
Security Best Practices

Never commit email credentials to version control. Use environment variables or secrets management.
  • Use App Passwords or API keys instead of account passwords
  • Restrict SMTP credentials to only send email (no read access)
  • Use a dedicated email account for ClassQuiz
  • Enable 2FA on your email account
  • Regularly rotate SMTP passwords
  • Monitor email sending logs for suspicious activity

​
Next Steps

Environment Variables

View all configuration options

OAuth Configuration

Set up social login providers

Build docs developers (and LLMs) love

Get started for freeTalk to us