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

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:

   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:

# 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)

mailpit:
  image: axllent/mailpit:latest
  ports:
    - "1025:1025"  # SMTP server
    - "8025:8025"  # Web UI

Rails Development Config (config/environments/development.rb)

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

rails generate mailer UserMailer welcome

Send Test Email from Rails Console

rails console

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

# Check Mailpit - email should appear!

Send Email from Your Code

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

Common Tasks

View Mailpit Web UI

task mailpit
# or just open http://localhost:8025

Check Mailpit Logs

task docker:logs:mailpit

Restart Mailpit

docker compose restart mailpit

Stop All Services

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:

docker compose ps

You should see turbovault_mailpit running.

Check Rails is configured correctly:

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:

tail -f log/development.log

Look for lines like:

Sent mail to user@example.com

Restart everything:

task docker:down
task docker:up
# Then restart Rails server

Can't Access Web UI?

Make sure port 8025 is not in use:

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:

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:

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
• Mailpit Documentation
• Rails Action Mailer Guide

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! 📧