Email Setup - PROVESA Web

PROVESA Web uses Nodemailer with Gmail to send password recovery emails. This guide covers the complete setup process.

Overview

The email system is configured in src/lib/server/auth.js as part of the Better Auth setup. It sends HTML-formatted password reset emails when users request to recover their accounts.

Gmail Prerequisites

A Gmail account (can be a Google Workspace account)
Two-factor authentication (2FA) enabled
App Password generated for SMTP access

Gmail requires App Passwords for third-party applications. You cannot use your regular Gmail password.

Step 1: Enable Two-Factor Authentication

App Passwords require 2FA to be enabled on your Google Account.

Enable 2FA

Go to Google Account Security
Under “How you sign in to Google”, click 2-Step Verification
Click Get Started
Follow the setup wizard:
- Enter your password
- Add a phone number
- Verify with a code sent to your phone
- Turn on 2-Step Verification

Step 2: Generate App Password

Once 2FA is enabled, generate an App Password for PROVESA Web.

Create App Password

Go to Google Account Security
Under “How you sign in to Google”, click 2-Step Verification
Scroll down and click App passwords
You may need to sign in again
In the “App passwords” page:
- Select app: Mail
- Select device: Other (Custom name)
- Enter name: PROVESA Web
- Click Generate
Copy the 16-character password (format: xxxx xxxx xxxx xxxx)

Save this password immediately - you won’t be able to see it again. If you lose it, you’ll need to generate a new one.

Step 3: Configure Environment Variables

Add your Gmail credentials to the .env file:

# Gmail credentials for password recovery
GMAIL_USER="no-reply@provesa.com"
GMAIL_APP_PASSWORD="abcd efgh ijkl mnop"

Environment Variables

GMAIL_USER

string

required

Your Gmail email address. This will be the sender address for password recovery emails.Example:

GMAIL_USER="no-reply@provesa.com"

Best Practice: Use a dedicated email like no-reply@ or support@ for automated emails.

GMAIL_APP_PASSWORD

string

required

The 16-character App Password generated in Step 2. You can include or omit spaces.Example:

GMAIL_APP_PASSWORD="abcd efgh ijkl mnop"

GMAIL_APP_PASSWORD="abcdefghijklmnop"

Email Configuration

The email system is configured in src/lib/server/auth.js:35-62 as part of Better Auth’s emailAndPassword plugin:

emailAndPassword: {
  enabled: true,
  async sendResetPassword({ user, url }) {
    const nodemailer = await import('nodemailer');
    const transporter = nodemailer.createTransport({
      service: 'gmail',
      auth: {
        user: env.GMAIL_USER,
        pass: env.GMAIL_APP_PASSWORD
      }
    });

    await transporter.sendMail({
      from: `"PROVESA SCC" <${env.GMAIL_USER}>`,
      to: user.email,
      subject: 'Recuperación de contraseña - PROVESA',
      html: `
        <div style="font-family: sans-serif; max-width: 600px; margin: auto;">
          <h2>Hola, ${user.name}</h2>
          <p>Recibimos una solicitud para restablecer tu contraseña en el Panel Administrativo de PROVESA.</p>
          <p>Haz clic en el siguiente botón para continuar:</p>
          <a href="${url}" style="display: inline-block; padding: 12px 24px; background-color: #1565C0; color: white; text-decoration: none; border-radius: 8px; font-weight: bold;">Restablecer Contraseña</a>
          <p style="margin-top: 20px; color: #666; font-size: 12px;">Si no solicitaste este cambio, puedes ignorar este correo de forma segura.</p>
        </div>
      `
    });
  }
}

Nodemailer Configuration

service

string

Set to gmail to use Gmail’s SMTP servers automatically. Nodemailer configures the correct host and port.

auth.user

string

Gmail email address from GMAIL_USER environment variable.

auth.pass

string

Gmail App Password from GMAIL_APP_PASSWORD environment variable.

Email Template

The password recovery email includes:

From: "PROVESA SCC" <your-gmail@gmail.com>
Subject: Recuperación de contraseña - PROVESA
Personalization: Uses the user’s name: Hola, ${user.name}
Reset Link: Button with the unique password reset URL
Security Note: Informs users they can ignore the email if they didn’t request it

Rate Limiting

To prevent abuse, password recovery requests are rate-limited in src/lib/server/auth.js:28-31:

customRules: {
  '/forget-password': {
    window: 60,    // 60 seconds
    max: 3,        // maximum 3 requests
  },
}

This allows:

3 password recovery requests per 60 seconds per IP address
Prevents email spam and brute-force attacks

Testing the Email Setup

1. Start Development Server

npm run dev

2. Trigger Password Recovery

Navigate to the login page
Click “Forgot password?”
Enter a valid user email
Submit the form

3. Check Email Delivery

Check the inbox of the email address you entered. You should receive an email from GMAIL_USER with the subject “Recuperación de contraseña - PROVESA”.

4. Verify Reset Link

Click the “Restablecer Contraseña” button in the email and verify:

It redirects to your application
The reset token is valid
You can set a new password

Customizing the Email Template

To customize the password recovery email, edit the HTML template in src/lib/server/auth.js:51-59:

html: `
  <div style="font-family: sans-serif; max-width: 600px; margin: auto;">
    <h2>Hola, ${user.name}</h2>
    <p>Your custom message here...</p>
    <a href="${url}" style="...">Reset Password</a>
  </div>
`

Template Variables

user.name - User’s display name
user.email - User’s email address
url - Unique password reset link (expires after use or timeout)

Alternative: SMTP Configuration

If you’re not using Gmail, you can configure any SMTP service:

const transporter = nodemailer.createTransport({
  host: 'smtp.example.com',
  port: 587,
  secure: false, // true for 465, false for other ports
  auth: {
    user: env.SMTP_USER,
    pass: env.SMTP_PASSWORD
  }
});

Popular SMTP Services

SendGrid - 100 emails/day free tier
Mailgun - 5,000 emails/month free tier
Amazon SES - Low cost, high deliverability
Postmark - Transactional email specialist
Resend - Modern email API with generous free tier

Troubleshooting

Invalid Credentials Error

Error: Invalid login: 535-5.7.8 Username and Password not accepted Solutions:

Verify GMAIL_APP_PASSWORD is correct (16 characters)
Ensure 2FA is enabled on your Google Account
Regenerate the App Password
Check that GMAIL_USER matches the account that generated the App Password

Connection Timeout

Error: Connection timeout Solutions:

Check your internet connection
Verify firewall isn’t blocking port 587 or 465
Try using a different network

Less Secure Apps

Error: Please log in via your web browser Solution: Google disabled “Less Secure Apps” access in May 2022. You must use App Passwords with 2FA enabled. Regular Gmail passwords no longer work for SMTP.

Email Not Received

Solutions:

Check spam/junk folder
Verify the recipient email address is correct
Check Gmail’s sent folder to confirm the email was sent
Verify rate limits aren’t being exceeded (3 requests per 60 seconds)

Rate Limit Exceeded

Error: Rate limit messages in console Solution: The /forget-password endpoint allows 3 requests per 60 seconds. Wait 60 seconds before trying again, or adjust the rate limit in src/lib/server/auth.js:28-31.

Security Best Practices

1. Use Dedicated Email Account

Create a dedicated Gmail account for sending automated emails:

no-reply@provesa.com
support@provesa.com
notifications@provesa.com

2. Rotate App Passwords

Periodically regenerate App Passwords:

Revoke old App Password in Google Account settings
Generate new App Password
Update GMAIL_APP_PASSWORD in .env
Restart application

3. Protect Environment Variables

Never commit .env files to version control
Use .env.example as a template (without real values)
Use secure secret management in production (e.g., AWS Secrets Manager, Railway secrets)

4. Monitor Email Sending

Monitor your Gmail account for:

Unusual sending patterns
Bounce rate increases
Spam complaints

Production Considerations

Gmail Sending Limits

Gmail has sending limits:

Free Gmail: 500 emails/day
Google Workspace: 2,000 emails/day

If you exceed these limits, consider using a dedicated transactional email service.

Email Deliverability

For production, improve deliverability:

Use custom domain - no-reply@provesa.com instead of @gmail.com
Configure SPF records - Authorize Gmail to send on your behalf
Set up DKIM - Digital signature verification
Add DMARC policy - Email authentication protocol

Transactional Email Service

For high-volume or mission-critical emails, migrate to:

Resend - Modern API, great DX
SendGrid - Established provider
Postmark - High deliverability
Amazon SES - Cost-effective at scale

Next Steps

Environment Variables - Complete environment variable reference
Database Setup - Configure PostgreSQL database

Get Started

Core Features

Configuration

Architecture

Guides

Documentation Index

​Overview

​Gmail Prerequisites

​Step 1: Enable Two-Factor Authentication

​Enable 2FA

​Step 2: Generate App Password

​Create App Password

​Step 3: Configure Environment Variables

​Environment Variables

​Email Configuration

​Nodemailer Configuration

​Email Template

​Rate Limiting

​Testing the Email Setup

​1. Start Development Server

​2. Trigger Password Recovery

​3. Check Email Delivery

​4. Verify Reset Link

​Customizing the Email Template

​Template Variables

​Alternative: SMTP Configuration

​Popular SMTP Services

​Troubleshooting

​Invalid Credentials Error

​Connection Timeout

​Less Secure Apps

​Email Not Received

​Rate Limit Exceeded

​Security Best Practices

​1. Use Dedicated Email Account

​2. Rotate App Passwords

​3. Protect Environment Variables

​4. Monitor Email Sending

​Production Considerations

​Gmail Sending Limits

​Email Deliverability

​Transactional Email Service

​Next Steps

Build docs developers (and LLMs) love

Overview

Gmail Prerequisites

Step 1: Enable Two-Factor Authentication

Enable 2FA

Step 2: Generate App Password

Create App Password

Step 3: Configure Environment Variables

Environment Variables

Email Configuration

Nodemailer Configuration

Email Template

Rate Limiting

Testing the Email Setup

1. Start Development Server

2. Trigger Password Recovery

3. Check Email Delivery

4. Verify Reset Link

Customizing the Email Template

Template Variables

Alternative: SMTP Configuration

Popular SMTP Services

Troubleshooting

Invalid Credentials Error

Connection Timeout

Less Secure Apps

Email Not Received

Rate Limit Exceeded

Security Best Practices

1. Use Dedicated Email Account

2. Rotate App Passwords

3. Protect Environment Variables

4. Monitor Email Sending

Production Considerations

Gmail Sending Limits

Email Deliverability

Transactional Email Service

Next Steps