# SMTP Setup Guide

## Overview

This guide explains how to configure SMTP for email functionality in the Location Tracker app.

## Prerequisites

- SMTP server credentials (Gmail, SendGrid, Mailgun, etc.)
- For Gmail: App Password (not regular password)

## Configuration Methods

### Method 1: Environment Variables (Fallback)

1. Copy `.env.example` to `.env.local`:
   ```bash
   cp .env.example .env.local
   ```

2. Generate encryption key:
   ```bash
   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   ```

3. Update SMTP settings in `.env.local`:
   ```env
   SMTP_HOST=smtp.gmail.com
   SMTP_PORT=587
   SMTP_SECURE=false
   SMTP_USER=your-email@gmail.com
   SMTP_PASS=your-app-password
   SMTP_FROM_EMAIL=noreply@example.com
   SMTP_FROM_NAME=Location Tracker
   ENCRYPTION_KEY=<generated-key-from-step-2>
   ```

### Method 2: Admin Panel (Recommended)

**IMPORTANT:** The `ENCRYPTION_KEY` environment variable is **required** for database-stored SMTP configuration. Generate and set it before using the admin panel:

```bash
# Generate encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Add to your environment variables (e.g., .env.local)
ENCRYPTION_KEY=<generated-key>
```

Steps:
1. Ensure `ENCRYPTION_KEY` is set in your environment
2. Restart the application server to load the new environment variable
3. Log in as admin
4. Navigate to **Settings** → **SMTP Settings**
5. Fill in SMTP configuration
6. Click **Test Connection** to verify
7. Click **Save Settings**

## Provider-Specific Setup

### Gmail

1. Enable 2-Factor Authentication
2. Generate App Password:
   - Go to Google Account → Security → 2-Step Verification → App Passwords
   - Select "Mail" and generate password
3. Use generated password in SMTP_PASS

Settings:
- Host: `smtp.gmail.com`
- Port: `587`
- Secure: `false` (uses STARTTLS)

### SendGrid

Settings:
- Host: `smtp.sendgrid.net`
- Port: `587`
- Secure: `false`
- User: `apikey`
- Pass: Your SendGrid API key

### Mailgun

Settings:
- Host: `smtp.mailgun.org`
- Port: `587`
- Secure: `false`
- User: Your Mailgun SMTP username
- Pass: Your Mailgun SMTP password

## Testing

### Via Script

```bash
node scripts/test-smtp.js your-email@example.com
```

### Via Admin Panel

1. Go to **Emails** page
2. Select a template
3. Click **Send Test Email**
4. Enter your email and send

## Troubleshooting

### Connection Timeout

- Check firewall settings
- Verify port is correct (587 for STARTTLS, 465 for SSL)
- Try toggling "Use TLS/SSL" setting

### Authentication Failed

- **For Gmail:** Use App Password, not account password
  - Generate at: https://myaccount.google.com/apppasswords
  - Enable 2FA first before creating App Passwords
- Verify username and password have no trailing spaces
- Check if SMTP is enabled for your account
- **Database config users:** Ensure `ENCRYPTION_KEY` is set and server was restarted
- If using database config after upgrading, click "Reset to Defaults" and re-enter credentials

### Emails Not Received

- Check spam/junk folder
- Verify "From Email" is valid
- Check provider sending limits

## Email Templates

Available templates:
- **Welcome Email**: Sent when new user is created
- **Password Reset**: Sent when user requests password reset

Templates can be previewed in **Admin → Emails**.

## Security Notes

- Passwords stored in database are encrypted using AES-256-GCM
- ENCRYPTION_KEY must be kept secret
- Never commit `.env.local` to git
- Use environment-specific SMTP credentials