Moving to github

docs/TESTING_EMAILS.md

@@ -0,0 +1,274 @@
+# 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! 📧