letter_opener_web Documentation

Mount the LetterOpenerWeb::Engine in your config/routes.rb file to enable the web interface. It is recommended to wrap this in a conditional check to ensure it only runs in non-production environments.

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

Add the gem to your development group in your Gemfile and run bundle to install it.

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

To use the gem in staging or pre-production environments to intercept emails:

1. Move the gem out of the development group in your Gemfile (e.g., place it in the top-level or a specific group).
2. Set config.action_mailer.delivery_method = :letter_opener_web in the appropriate config/environments/<env>.rb.
3. Enable the route in routes.rb for that environment.

Note for Heroku users: This will only work if your app has exactly one Dyno and does not send emails from background jobs.

# Gemfile
gem 'letter_opener_web'

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

  # For environments using RAILS_ENV=production in staging
  mount LetterOpenerWeb::Engine, at: "/letter_opener" unless ENV["PRODUCTION_FOR_REAL"]
end

To use the web interface as your primary way to view emails (and to avoid launchy errors in environments like Docker or Vagrant), set :letter_opener_web as your action_mailer.delivery_method in config/environments/development.rb.

config.action_mailer.delivery_method = :letter_opener_web

You can change the directory where sent emails are stored by setting config.letters_location within a LetterOpenerWeb.configure block in an initializer or your environment configuration.

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

Control whether LetterOpenerWeb applies a CSS-based color inversion strategy to approximate dark mode for email templates. This is disabled by default to prevent conflicts with existing prefers-color-scheme styles in email templates.

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

The letter_opener_web engine automatically registers itself as an ActionMailer delivery method named :letter_opener_web. To use it, you must set your config.action_mailer.delivery_method to :letter_opener_web in your Rails environment configuration.

By default, the delivery method uses the location defined in LetterOpenerWeb.config.letters_location to store or reference letters.

# In config/environments/development.rb
config.action_mailer.delivery_method = :letter_opener_web

Use the LetterOpenerWeb.configure method to set global configuration options. This is typically done in a Rails initializer (e.g., config/initializers/letter_opener_web.rb).

Available configuration options:

• letters_location: The directory where intercepted emails are stored. Defaults to Rails.root.join('tmp', 'letter_opener').
• auto_dark_mode: A boolean determining if dark mode is automatically enabled. Defaults to false.

LetterOpenerWeb.configure do |config|
  config.letters_location = Rails.root.join('tmp', 'custom_emails')
  config.auto_dark_mode = true
end