Developing Ruby on Rails applications often involves sending emails, but during development, this task can get tricky. You wouldn’t want to accidentally send test emails to actual users. That’s where the letter_opener gem comes into play. This gem lets you preview emails in your browser instead of sending them, making life a whole lot easier.

First things first, to start using letter_opener, you need to add it to your Rails application’s Gemfile. This gem should only be used in the development environment, so it’s best to group it accordingly. Here’s how it looks:

group :development do
  gem 'letter_opener'
end

Once that’s done, run bundle install to get it installed.

Next, you need to configure your development environment to use letter_opener for email previews. Open your config/environments/development.rb file and add these lines:

config.action_mailer.delivery_method = :letter_opener
config.action_mailer.perform_deliveries = true

You might also want to set the default URL options:

config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }

This config sets the delivery method to letter_opener and makes sure email deliveries are enabled. Be sure to change the host and port values to match your application’s setup.

Now with your gem installed and configured, you can preview emails right in your browser. Whenever your application sends an email in the development environment, letter_opener jumps in and opens it in a new tab. To trigger an email preview, you need to send an email from your app. For instance, suppose you have a mailer class like this:

class PostMailer < ApplicationMailer
  def send_issue(post)
    @post = post
    mail(to: "user@example.com", subject: @post.title)
  end
end

You can call the mailer method in your controller or any other spot in your app where you need to send an email:

PostMailer.with(post: @post).send_issue.deliver_now

After triggering the email, a new browser tab will pop open, showing you a preview of the email thanks to letter_opener.

The letter_opener is quite customizable too. You can specify where the email previews are saved or tweak the URL path. For example, to change the default storage location, do this:

LetterOpener.configure do |config|
  config.location = Rails.root.join('tmp', 'my_mails')
end

You can also change the message template to show only the message body without any extra stuff:

LetterOpener.configure do |config|
  config.message_template = :light
end

If you’re using the Windows Subsystem for Linux (WSL) and the default file URI scheme doesn’t work, you can set a custom scheme like this:

LetterOpener.configure do |config|
  config.file_uri_scheme = 'file://///wsl$/Ubuntu-18.04'
end

By default, letter_opener uses Launchy to open emails in your default browser. But if you prefer a specific browser, set the BROWSER environment variable:

BROWSER='/Applications/Google Chrome Canary.app' rails s

This makes sure emails open in Google Chrome instead of your default browser.

Let’s not forget those who aren’t using Rails. You can still set up letter_opener with the Mail gem. Here’s how:

require "letter_opener"
Mail.defaults do
  delivery_method LetterOpener::DeliveryMethod, location: File.expand_path('../tmp/letter_opener', __FILE__)
end

Pony gem users can set it up similarly:

require "letter_opener"
Pony.options = { via: LetterOpener::DeliveryMethod, via_options: { location: File.expand_path('../tmp/letter_opener', __FILE__) } }

And if ActionMailer is your choice but without Rails, add the delivery method like this:

require "letter_opener"
ActionMailer::Base.add_delivery_method :letter_opener, LetterOpener::DeliveryMethod, location: File.expand_path('../tmp/letter_opener', __FILE__)
ActionMailer::Base.delivery_method = :letter_opener

Running your application in a Docker container or VM might pose some issues because letter_opener relies on Launchy to open the browser. You can bypass errors by setting these environment variables:

LAUNCHY_DRY_RUN=true
BROWSER=/dev/null

Alternatively, you could use letter_opener_web for a web interface, making it easier to browse sent emails in containerized environments. To set it up, add the gem to your Gemfile:

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

Then, mount the engine in your routes.rb file:

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

Just ensure you have the :letter_opener delivery method configured. After sending an email, you can head to http://localhost:3000/letter_opener to check them out.

So, the letter_opener gem is super handy for Rails developers keen on smooth email testing. By following these easy steps, you prevent your app from accidentally sending out real emails during development. And with its various customization options and web interface support, letter_opener makes email previewing a breeze. Whether working locally or in a containerized setup, this gem lets you focus on what’s really important – developing your application!