Maily is a Rails Engine to manage, test and navigate through all your email templates of your app, being able to preview them directly in your browser.
Maily automatically picks up all your emails and make them accessible from a kind of dashboard.
- Mountable engine
- Visual preview in the browser (attachments as well)
- Template edition (only in development)
- Email delivery
- Easy way (aka
Hooks) to define and customize data for emails - Email versions
- Flexible authorization system
- Minimalistic and clean interface
- Generator to handle a comfortable installation
Add this line to your Gemfile and then run bundle install:
gem 'maily'Run generator:
> rails g maily:install
This generator runs some tasks for you:
- Mounts the engine (to
/mailyby default) in your routes - Adds an initializer (into
config/initializers/maily.rb) to customize some settings - Adds a file (into
lib/maily_hooks.rb) to define hooks
You should use the setup method to configure and customize Maily settings:
# config/initializers/maily.rb
Maily.setup do |config|
# On/off engine
# config.enabled = !Rails.env.production?
# Allow templates edition
# config.allow_edition = !Rails.env.production?
# Allow deliveries
# config.allow_delivery = !Rails.env.production?
# Your application available_locales (or I18n.available_locales) by default
# config.available_locales = [:en, :es, :pt, :fr]
# Run maily under different controller ('ActionController::Base' by default)
# config.base_controller = '::AdminController'
# Configure hooks path
# config.hooks_path = 'lib/maily_hooks.rb'
# Http basic authentication (nil by default)
# config.http_authorization = { username: 'admin', password: 'secret' }
# Customize welcome message
# config.welcome_message = "Welcome to our email testing platform. If you have any problem, please contact support team at [email protected]."
endYou can use the following format too:
Maily.enabled = ENV['MAILY_ENABLED']
Maily.allow_edition = falseThis feature was designed for the development environment. Since it's based on just a file edition, and while running in production mode, code is not reloaded between requests, Rails doesn't take into account your changes (without restarting the server). Actually, allowing arbitrary Ruby code evaluation is potentially dangerous, and that's not a good idea in production.
So, template edition is not allowed outside of the development environment.
Most of emails need to populate some data to consume it and do interesting things. Hooks are used to define this data via a little DSL. Hooks also accept "callable" objects to lazy load variables/data, so each email will evaluate its hooks on demand. Example:
# lib/maily_hooks.rb
user = User.new(email: '[email protected]')
lazy_user = -> { User.with_comments.first } # callable object, lazy evaluation
comment = Struct.new(:body).new('Lorem ipsum') # stub way
service = FactoryGirl.create(:service) # using fixtures with FactoryGirl
Maily.hooks_for('Notifier') do |mailer|
mailer.register_hook(:welcome, user, template_path: 'users')
mailer.register_hook(:new_comment, lazy_user, comment)
end
Maily.hooks_for('PaymentNotifier') do |mailer|
mailer.register_hook(:invoice, user, service)
endNote that you are able to override the template_path and the template_name like can be done in Rails. You must pass these options as a hash and last argument:
Maily.hooks_for('YourMailerClass') do |mailer|
mailer.register_hook(:a_random_email, template_path: 'notifications')
mailer.register_hook(:another_email, template_name: 'email_base')
endYou can add versions for special emails. This is useful in some cases where template content depends on the parameters you provide, for instance, a welcome message for trial accounts and gold accounts.
free_trial_account = -> { Account.free_trial.first }
gold_account = -> { Account.gold.first }
Maily.hooks_for('Notifier') do |mailer|
mailer.register_hook(:welcome, free_trial_account, version: 'Free trial account')
mailer.register_hook(:welcome, gold_account, version: 'Gold account')
endYou can add a description to any email and it will be displayed along with its preview. This is useful in some cases like: someone from another team, for example, a marketing specialist, visiting Maily to review some texts and images; they can easily understand when this email is sent by the system.
Maily.hooks_for('BookingNotifier') do |mailer|
mailer.register_hook(:accepted, description: "This email is sent when a reservation has been accepted by the system." )
endYou are also able to hide emails:
Maily.hooks_for('Notifier') do |mailer|
mailer.hide_email(:sensible_email, :secret_email)
endSupport for ActionMailer::Parameterized is possible via with_params hash:
message = -> { 'Hello!' }
Maily.hooks_for('Notifier') do |mailer|
mailer.register_hook(:new_message, with_params: { message: message })
endIf you want to register and display in the UI, emails from external sources, like for example a gem, you can do it by adding a hook. Example:
Maily.hooks_for('Devise::Mailer') do |mailer|
mailer.hide_email(:unlock_instructions)
mailer.register_hook(:reset_password_instructions, user, 'random_token')
mailer.register_hook(:confirmation_instructions, user, 'random_token')
mailer.register_hook(:password_change, user)
endBasically, you have 2 ways to restrict access to the Maily section. You can even combine both.
By default Maily runs under ActionController::Base, but you are able to customize that parent controller (Maily.base_controller option) in order to achieve (using, for example, before_action blocks) a kind of access control system. For example, set a different base controller:
Maily.base_controller = '::SuperAdminController'And then write your own authorization rules in this defined controller:
class SuperAdminController < ActionController::Base
before_action :maily_authorized?
private
def maily_authorized?
current_user.admin? || raise("You don't have access to this section!")
end
endYou can also authorize yours users via HTTP basic authentication, simply use this option:
Maily.http_authorization = { username: 'admin', password: 'secret' }Rails 4.1 introduced a built-in mechanism to preview the application emails. It is in fact, a port of basecamp/mail_view gem to the core.
Alternatively, there are more gems out there to get a similar functionality, but with different approaches and features. Like for example: ryanb/letter_opener, sj26/mailcatcher or glebm/rails_email_preview.
Any kind of feedback, bug report, idea or enhancement are really appreciated 🎉
To contribute, just fork the repo, hack on it and send a pull request. Don't forget to add tests for behaviour changes and run the test suite:
> bundle exec rspec
Run the test suite against all supported versions:
> bundle exec appraisal install
> bundle exec appraisal rspec
Run specs against specific version:
> bundle exec appraisal rails-6.0 rspec
Start a sample Rails app (source code) with Maily integrated:
> bundle exec rake web # PORT=4000 (default: 3000)
Copyright (c) Marc Anguera. Maily is released under the MIT License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent