Skip to content

Latest commit

 

History

History
262 lines (180 loc) · 8.67 KB

README.md

File metadata and controls

262 lines (180 loc) · 8.67 KB
Raw

GitHub

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.

Features:

  • 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

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 /maily by 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

Initialization and configuration

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]."
end

You can use the following format too:

Maily.enabled = ENV['MAILY_ENABLED']
Maily.allow_edition = false

Templates edition (allow_edition option)

This 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.

Hooks

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)
end

Note 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')
end

Email versions

You 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')
end

Email description

You 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." )
end

Hide emails

You are also able to hide emails:

Maily.hooks_for('Notifier') do |mailer|
  mailer.hide_email(:sensible_email, :secret_email)
end

Use params

Support 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 })
end

External emails

If 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)
end

Authorization

Basically, you have 2 ways to restrict access to the Maily section. You can even combine both.

Custom base controller

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
end

HTTP basic authentication

You can also authorize yours users via HTTP basic authentication, simply use this option:

Maily.http_authorization = { username: 'admin', password: 'secret' }

Notes

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.

Development

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

Demo

Start a sample Rails app (source code) with Maily integrated:

> bundle exec rake web # PORT=4000 (default: 3000)

License

Copyright (c) Marc Anguera. Maily is released under the MIT License.