Better Mailer Previews — A lightweight Rails engine for improved email previews.

This is the jbox-web fork of harrison-broadbent/better_mailer_previews, maintained for current Ruby and Rails versions. It is not published to RubyGems: install it from this repository.

Requires Ruby >= 3.2 and Rails >= 7.2. Tested against Rails 7.2, 8.0 and 8.1.

Better Mailer Previews is a Ruby on Rails gem that makes previewing all your ActionMailer email templates easier.

This gem/engine builds on top of native Rails mailer previews, with a few key enhancements like —

• Shows all your previews live on the homepage
• Easily resize individual mailers, for testing responsive layouts
• Forward your previews to an email address (uses the default ActionMailer delivery method for your app).
• Fully compatible with, and can live alongside, native Rails ActionMailer Previews
• Supports namespaced mailers (think User::SignupMailer) as of v1.0.1

Here's a little demo I've put together ↓

Why did I build this?

I've used native Rails mailer previews extensively for building my ActionMailer email templates, but they're pretty barebones and lacking. In particular, I wanted a way to bulk-preview templates (rather than checking them one by one). I also wanted to be able to easily resize the email container for testing responsive layouts.

This gem is my idea brought to life, and I hope you'll find it useful!

Getting Started

1. Add this line to the development group in your application's Gemfile:

group :development do
  ...
  gem "better_mailer_previews", git: "https://github.com/jbox-web/better_mailer_previews.git"
end

2. And then execute:

$ bundle

3. Finally, you need to mount this engine in your routes.rb file —

# routes.rb

Rails.application.routes.draw do
  mount BetterMailerPreviews::Engine, at: "/better_mailer_previews" if Rails.env.development?
  ...
end

4. Run your Rails app, and visit localhost:3000/better_mailer_previews.
5. Profit ✨

Sending email previews to an email address

This gem let's you send your email previews to an email address, using whatever default delivery method you have configured.

Better Mailer Previews sends it's emails using whichever config.action_mailer.delivery_method is defined for the environment. For example, if you're using Mailhog in development to test your emails, you might have a configuration like this —

# config/environments/development.rb
#
Rails.application.configure do
  ...
  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = {address: "127.0.0.1", port: 1025}
  config.action_mailer.raise_delivery_errors = false
end

In this case, Better Mailer Previews will send it's emails to Mailhog too (since it uses your existing configuration). If you want to send emails to a live inbox (like your personal email), you'd need to configure a live delivery method for the current environment.

How can I get previews to show up for my mailers?

This engine will display all the Actionmailer Previews defined in the host Ruby on Rails app. These are the mailer previews you've defined in test/mailers/previews, for use with native Actionmailer Previews.

For all the mailers you'd like to preview, you need to set up the corresponding ActionMailer::Preview class. Once you've done that, this engine will automatically pull them all in and let you preview them!

Asset pipeline

The engine ships a single stylesheet and works with Sprockets, with Propshaft, and with no asset pipeline at all — its precompile hint is applied only when the host actually uses Sprockets. You do not need to add sprockets-rails for this gem.

Other things to note

• You need an internet connection for this to engine to work properly. This engine tries to load the TailwindCSS package via a CDN, to handle the app styling. Your browser will cache the package after you first download it though, which is handy.

More from me

If you like this gem, you'll probably like some of my other work (all Ruby on Rails stuff) —

• RailsNotes, my Ruby on Rails blog
• My Ruby on Rails Newsletter
• RAILSG, a command builder for Rails generator commands
• RailsNotes UI, a library of ActionMailer email templates and components

If you want updates, you can also follow me on Twitter

Contributing

Run the suite with bin/rspec and the linter with bin/rubocop. The gem is tested against several Rails versions through appraisal: BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bin/rspec.

License

The gem is available as open source under the terms of the MIT License.