turbovault-app/docs/TESTING_EMAILS.md

# Testing Emails Locally with Mailpit

TurboVault is configured to use **Mailpit** for local email testing. Mailpit captures all emails sent by the application so you can view them in a web interface without actually sending real emails.

## Quick Start

### 1. Start the Services

```bash
task docker:up
```

This starts both PostgreSQL and Mailpit. You'll see:
```
PostgreSQL: localhost:5432
Mailpit UI: http://localhost:8025
```

### 2. Access Mailpit Web UI

Open your browser and visit:
```
http://localhost:8025
```

You'll see the Mailpit interface where all emails will appear.

### 3. Test Password Reset Email

1. Start your Rails server:
   ```bash
   task server
   ```

2. Visit http://localhost:3000

3. Click "Login" then "Forgot your password?"

4. Enter any email address from a user account you created

5. Check Mailpit at http://localhost:8025 - you'll see the password reset email!

6. Click on the email to view it (both HTML and text versions)

7. Click the "Reset My Password" link in the email to test the flow

## Features

### Web Interface (http://localhost:8025)

- **View all emails** sent by your Rails app
- **Search emails** by recipient, subject, or content
- **View both HTML and text versions** of emails
- **Test responsive design** - resize the preview
- **Download emails** as .eml files
- **View email headers** and technical details
- **Clear all emails** when you want to start fresh

### API Access

Mailpit also has an API if you want to automate testing:

```bash
# Get all emails
curl http://localhost:8025/api/v1/messages

# Get specific email
curl http://localhost:8025/api/v1/message/MESSAGE_ID

# Delete all emails
curl -X DELETE http://localhost:8025/api/v1/messages
```

## Configuration

The configuration is already set up in:

### Docker Compose (`docker-compose.yml`)
```yaml
mailpit:
  image: axllent/mailpit:latest
  ports:
    - "1025:1025"  # SMTP server
    - "8025:8025"  # Web UI
```

### Rails Development Config (`config/environments/development.rb`)
```ruby
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: "localhost",
  port: 1025,
  enable_starttls_auto: false
}
```

## Testing Other Emails

### Create a New Mailer

```bash
rails generate mailer UserMailer welcome
```

### Send Test Email from Rails Console

```bash
rails console

# Send password reset
user = User.first
PasswordResetMailer.reset_password(user).deliver_now

# Check Mailpit - email should appear!
```

### Send Email from Your Code

```ruby
# In a controller or model
PasswordResetMailer.reset_password(user).deliver_later
```

## Common Tasks

### View Mailpit Web UI
```bash
task mailpit
# or just open http://localhost:8025
```

### Check Mailpit Logs
```bash
task docker:logs:mailpit
```

### Restart Mailpit
```bash
docker compose restart mailpit
```

### Stop All Services
```bash
task docker:down
```

## Tips

1. **Keep Mailpit open** in a browser tab during development
2. **Emails appear instantly** - no delay like real SMTP
3. **No email quota limits** - send as many test emails as you want
4. **All emails are captured** - can't accidentally send to real addresses
5. **Automatic cleanup** - emails are cleared when you restart Mailpit
6. **Mobile testing** - Mailpit UI is responsive, test on different screen sizes

## Troubleshooting

### Emails Not Appearing?

**Check Mailpit is running:**
```bash
docker compose ps
```

You should see `turbovault_mailpit` running.

**Check Rails is configured correctly:**
```bash
rails console
> Rails.application.config.action_mailer.delivery_method
=> :smtp
> Rails.application.config.action_mailer.smtp_settings
=> {:address=>"localhost", :port=>1025, :enable_starttls_auto=>false}
```

**Check Rails logs:**
```bash
tail -f log/development.log
```

Look for lines like:
```
Sent mail to user@example.com
```

**Restart everything:**
```bash
task docker:down
task docker:up
# Then restart Rails server
```

### Can't Access Web UI?

Make sure port 8025 is not in use:
```bash
lsof -i :8025
```

If something else is using it, stop that service or change Mailpit's port in `docker-compose.yml`.

### Emails Sent But Not in Mailpit?

Check that Rails is actually sending to localhost:1025:
```bash
rails console
> ActionMailer::Base.delivery_method
=> :smtp
> ActionMailer::Base.smtp_settings
=> {:address=>"localhost", :port=>1025, ...}
```

## Production Configuration

When you deploy to production, you'll need real SMTP settings. Update `config/environments/production.rb`:

```ruby
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: ENV['SMTP_ADDRESS'],
  port: ENV['SMTP_PORT'],
  user_name: ENV['SMTP_USERNAME'],
  password: ENV['SMTP_PASSWORD'],
  authentication: 'plain',
  enable_starttls_auto: true
}
```

Common SMTP providers:
- **SendGrid** - Free tier: 100 emails/day
- **Mailgun** - Free tier: 5,000 emails/month
- **Postmark** - Free tier: 100 emails/month
- **AWS SES** - $0.10 per 1,000 emails
- **Gmail SMTP** - Free but limited

## Mailpit vs Other Tools

### Mailpit (Current)
✅ Modern, actively maintained
✅ Fast and lightweight
✅ Great UI
✅ Built-in API

### MailHog (Alternative)
⚠️ No longer actively maintained
⚠️ Older UI
✅ Still works fine

### MailCatcher (Alternative)
⚠️ Requires Ruby installation
⚠️ Less modern

We chose Mailpit because it's actively maintained and has the best developer experience.

## Resources

- [Mailpit GitHub](https://github.com/axllent/mailpit)
- [Mailpit Documentation](https://mailpit.axllent.org/)
- [Rails Action Mailer Guide](https://guides.rubyonrails.org/action_mailer_basics.html)

## Summary

**For Local Development:**
- Mailpit captures all emails at http://localhost:8025
- No real emails sent
- Perfect for testing email templates and flows
- Already configured, just `task docker:up` and go!

**For Production:**
- Configure real SMTP provider in environment variables
- Set SMTP_ADDRESS, SMTP_USERNAME, SMTP_PASSWORD
- Emails will be sent for real

Happy testing! 📧