letter_opener_web

letter_opener_web

Gives letter_opener an interface for browsing sent emails.

Installation

First add the gem to your development environment and run the bundle command to install it.

group :development do
  gem 'letter_opener_web', '~> 3.0'
end

Usage

Add to your routes.rb:

Your::Application.routes.draw do
  mount LetterOpenerWeb::Engine, at: "/letter_opener" if Rails.env.development?
end

And make sure you have :letter_opener delivery method configured for your app. Then visit http://localhost:3000/letter_opener after sending an email and have fun.

If you are running the app from a Vagrant machine or Docker container, you might want to skip letter_opener’s launchy calls and avoid messages like these:

12:33:42 web.1  | Failure in opening /vagrant/tmp/letter_opener/1358825621_ba83a22/rich.html
with options {}: Unable to find a browser command. If this is unexpected, Please rerun with
environment variable LAUNCHY_DEBUG=true or the '-d' commandline option and file a bug at
https://github.com/copiousfreetime/launchy/issues/new

In that case (or if you really just want to browse mails using the web interface and don’t care about opening emails automatically), you can set :letter_opener_web as your delivery method on your config/environments/development.rb:

config.action_mailer.delivery_method = :letter_opener_web

Configuration

letters_location

If you’re using :letter_opener_web as your delivery method, you can change the location of the letters by adding the following to an initializer (or in development.rb):

LetterOpenerWeb.configure do |config|
  config.letters_location = Rails.root.join('your', 'new', 'path')
end

auto_dark_mode

You can control whether LetterOpenerWeb applies an automatic dark mode color inversion strategy when previewing emails.

By default, this is disabled to avoid conflicts with email templates that already implement their own prefers-color-scheme styling.

LetterOpenerWeb.configure do |config|
  config.auto_dark_mode = true
end

When enabled, LetterOpenerWeb applies a CSS-based inversion strategy to approximate dark mode for templates that do not define their own styles, similar to high-contrast or browser-level color inversion.

Usage on pre-production environments

Some people use this gem on staging / pre-production environments to avoid having real emails being sent out. To set that up you’ll need to:

1. Move the gem out of the development group in your Gemfile
2. Set config.action_mailer.delivery_method on the appropriate config/environments/<env>.rb
3. Enable the route for the environments on your routes.rb.

In other words, your Gemfile will have:

gem 'letter_opener_web'

And your routes.rb:

Your::Application.routes.draw do
  # If you have a dedicated config/environments/staging.rb
  mount LetterOpenerWeb::Engine, at: "/letter_opener" if Rails.env.staging?

  # If you use RAILS_ENV=production in staging environments, you'll need another
  # way to disable it in "real production"
  mount LetterOpenerWeb::Engine, at: "/letter_opener" unless ENV["PRODUCTION_FOR_REAL"]
end

NOTICE: Using this gem on Heroku will only work if your app has just one Dyno and does not send emails from background jobs. For updates on this matter please subscribe to GH-35

Acknowledgements

Special thanks to @alexrothenberg for some ideas on this pull request and @pseudomuto for keeping the project alive for a few years.

Contributing

1. Fork it and run bin/setup
2. Create your feature branch (git switch -c my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request