Email Verification & Password Reset

FastCMS includes a complete email verification and password reset system for both admin users and auth collection users.

SMTP Configuration

Configure your SMTP settings in the .env file:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=noreply@fastcms.dev
SMTP_FROM_NAME=FastCMS

Gmail Setup:

Enable 2-factor authentication on your Google account
Generate an App Password at myaccount.google.com/apppasswords
Use the app password in SMTP_PASSWORD

Other SMTP Providers:

SendGrid — smtp.sendgrid.net on port 587
Mailgun — smtp.mailgun.org on port 587
AWS SES — your SES SMTP endpoint

Email Verification Flow

1. Register (email sent automatically)

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "password_confirm": "SecurePass123!",
    "name": "John Doe"
  }'

The user receives an email with a link like:

http://localhost:8000/verify?token=abc123...

2. Verify Email

curl -X POST http://localhost:8000/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "abc123..."}'

3. Resend Verification Email

curl -X POST http://localhost:8000/api/v1/auth/resend-verification \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Verification tokens are valid for 24 hours.

Password Reset Flow

1. Request Password Reset

curl -X POST http://localhost:8000/api/v1/auth/request-password-reset \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Response:

{
  "message": "If the email exists, a password reset link has been sent"
}

2. Reset Password

curl -X POST http://localhost:8000/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "xyz789...",
    "new_password": "NewSecurePass456!",
    "password_confirm": "NewSecurePass456!"
  }'

Auth Collections Email Support

Password reset also works for auth collections:

curl -X POST http://localhost:8000/api/v1/auth/request-password-reset \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "collection": "customers"
  }'

Token Security

Verification Tokens — valid for 24 hours, single-use
Password Reset Tokens — valid for 1 hour, single-use
Tokens are cryptographically secure random strings
Used tokens are marked and cannot be reused

Troubleshooting

Problem	Solution
Email not sending	Check SMTP credentials in `.env`
Gmail "Less Secure Apps" error	Use App Passwords (not less secure apps)
Email goes to spam	Configure SPF/DKIM records for your domain

Email Verification & Password Reset

On this page