# Email Setup for User Auth Service

## Overview

The User Auth Service sends verification emails when users register. This document explains how to configure email functionality.

## Problem

If emails are not being sent, it's likely due to missing email configuration. The service will show errors like:
- "Email configuration is missing"
- "Failed to create email transporter"
- "Failed to send verification email"

## Quick Fix

### Option 1: Use the Setup Script (Recommended)

```bash
cd automated-dev-pipeline/services/user-auth
./setup-email.sh
```

This interactive script will guide you through the setup process.

### Option 2: Manual Configuration

1. **Create .env file**:
   ```bash
   cd automated-dev-pipeline/services/user-auth
   cp env.example .env
   ```

2. **Edit .env file** with your email credentials

## Email Configuration Options

### Gmail (Recommended for Development)

1. **Enable 2-Step Verification** on your Google account
2. **Generate App Password**:
   - Go to https://myaccount.google.com/security
   - Click "App passwords"
   - Generate password for "Mail"
3. **Update .env file**:
   ```env
   GMAIL_USER=your-email@gmail.com
   GMAIL_APP_PASSWORD=your-16-char-app-password
   SMTP_FROM=your-email@gmail.com
   ```

### Custom SMTP Server

```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-password
SMTP_FROM=your-email@gmail.com
```

### Development Mode (Mock Emails)

If you don't want to set up real emails in development:

```env
NODE_ENV=development
# No email credentials needed
```

The service will use mock emails and log what would be sent.

## Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `GMAIL_USER` | Gmail email address | If using Gmail | - |
| `GMAIL_APP_PASSWORD` | Gmail app password | If using Gmail | - |
| `SMTP_HOST` | SMTP server hostname | If using SMTP | - |
| `SMTP_PORT` | SMTP server port | If using SMTP | 587 |
| `SMTP_USER` | SMTP username | If using SMTP | - |
| `SMTP_PASS` | SMTP password | If using SMTP | - |
| `SMTP_FROM` | From email address | Yes | GMAIL_USER |
| `NODE_ENV` | Environment mode | No | development |

## Testing Email Configuration

### 1. Check Service Logs

```bash
# View email-related logs
docker-compose logs user-auth | grep -E "(Email|SMTP|Gmail|Mock)"

# View all logs
docker-compose logs user-auth
```

### 2. Test Registration

1. Visit `http://localhost:3001/signup`
2. Register a new user
3. Check logs for email status

### 3. Expected Log Output

**Success (Real Email)**:
```
✅ Email transporter created successfully
📧 Using Gmail configuration
✅ Verification email sent successfully to user@example.com
✉️ Email sent to user@example.com. MessageID: <message-id>
```

**Development Mode (Mock Email)**:
```
⚠️ No email configuration found. Using mock transporter for development.
📧 [MOCK] Email would be sent: { to: 'user@example.com', subject: '...', from: '...' }
```

## Troubleshooting

### Common Issues

1. **"Email configuration is missing"**
   - Solution: Set up email credentials in .env file

2. **"Authentication failed"**
   - Solution: Check username/password, enable 2FA for Gmail

3. **"Connection timeout"**
   - Solution: Check firewall, use correct port (587 for Gmail)

4. **"Invalid credentials"**
   - Solution: Use App Password, not regular Gmail password

### Debug Steps

1. **Check environment variables**:
   ```bash
   docker-compose exec user-auth env | grep -E "(SMTP|GMAIL|EMAIL)"
   ```

2. **Test email service directly**:
   ```bash
   docker-compose exec user-auth node -e "
   require('dotenv').config();
   const { sendMail } = require('./src/utils/email');
   sendMail('test@example.com', 'Test', 'Test email', '<h1>Test</h1>')
     .then(() => console.log('Email sent'))
     .catch(err => console.error('Email failed:', err.message));
   "
   ```

3. **Verify network connectivity**:
   ```bash
   docker-compose exec user-auth ping smtp.gmail.com
   ```

## Security Notes

- **Never commit .env files** to version control
- **Use App Passwords** for Gmail, not regular passwords
- **Restrict SMTP access** to trusted IPs in production
- **Rotate credentials** regularly

## Production Considerations

- Use dedicated email service (SendGrid, Mailgun, etc.)
- Set up proper SPF/DKIM records
- Monitor email delivery rates
- Implement email templates
- Add retry logic for failed emails

## Support

If you continue having issues:

1. Check the service logs for detailed error messages
2. Verify your email credentials are correct
3. Test with a simple email client first
4. Check if your email provider blocks automated emails