maily::mailbox: Rails Engine to preview emails in the browser

Maily 是一款 Rails 引擎，用于管理、测试和导航您应用程序中的所有电子邮件模板，并能够直接在浏览器中预览它们。

Maily 会自动检索您的所有电子邮件，并使它们在类似仪表板的界面中易于访问。

特点：

• 可挂载的引擎
• 在浏览器中可视化预览（包括附件）
• 模板编辑（仅限开发环境）
• 电子邮件发送
• 通过钩子（Hooks）定义和自定义电子邮件数据的便捷方式
• 电子邮件版本管理
• 灵活的授权系统
• 极简且界面清爽
• 安装向导，使安装过程更加舒适

安装

将以下行添加到您的 Gemfile 文件中，然后执行 bundle install：

gem 'maily'

运行生成器：

> rails g maily:install

这个生成器会为您执行以下任务：

• 在您的路由中挂载引擎（默认挂载至 /maily）
• 添加一个初始化器（至 config/initializers/maily.rb），以便自定义一些设置
• 添加一个文件（至 lib/maily_hooks.rb），用于定义钩子

初始化和配置

您应该使用 setup 方法来配置和定制 Maily 的设置：

# 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 support@example.com."
end

您也可以使用以下格式：

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

模板编辑功能（allow_edition 选项）

此功能专为 development 环境设计。因为它仅基于文件编辑，而在 production 模式运行时，代码不会在请求之间重新加载，Rails 将不会考虑您的更改（除非重启服务器）。实际上，允许任意 Ruby 代码执行存在潜在风险，因此在 production 环境中并不是一个好主意。

因此，模板编辑不允许在 development 环境之外进行。

钩子

大多数电子邮件需要填充一些数据以供使用并执行一些有趣的操作。钩子用于通过一个小型 DSL 定义这些数据。钩子还接受 "可调用" 对象以延迟加载变量/数据，因此每个电子邮件将按需评估其钩子。例如：

# lib/maily_hooks.rb

user = User.new(email: 'user@example.com')
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

请注意，您可以像在Rails中那样覆盖 template_path 和 template_name。您必须将这些选项作为哈希值传递，作为最后一个参数：

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

邮件版本

您可以为特定邮件添加版本。这在某些情况下非常有用，比如模板内容依赖于您提供的参数，例如为新用户和金牌账户提供的欢迎信息。

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

邮件描述

您可以为任意邮件添加描述，该描述将与邮件预览一同显示。这在某些情况下非常有用，例如：来自其他团队的成员，比如市场营销专员，访问Maily审阅某些文本和图片时；他们可以轻松地理解这封邮件何时由系统发送。

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

隐藏电子邮件

您还可以选择隐藏电子邮件地址：

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

使用 params

通过 with_params 哈希，可以实现对于 ActionMailer::Parameterized 的支持：

message = -> { 'Hello!' }

Maily.hooks_for('Notifier') do |mailer|
  mailer.register_hook(:new_message, with_params: { message: message })
end

外部邮件处理

若您希望注册并显示在用户界面中来自外部源（例如某个gem）的邮件，可以通过添加一个钩子（hook）来实现。例如：

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

授权

基本上，您有两种方法可以限制对 Maily 部分的访问。您甚至可以同时使用这两种方法。

自定义基础控制器

默认情况下，Maily 在 ActionController::Base 下运行，但您可以通过自定义父控制器（Maily.base_controller 选项）来设置访问控制系统（例如使用 before_action 块）。例如，设置一个不同的基础控制器：

Maily.base_controller = '::SuperAdminController'

然后在定义的控制器中编写您自己的授权规则：

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基本认证

您还可以通过HTTP基本认证来授权您的用户，只需使用此选项即可：

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

注意事项

Rails 4.1 引入了一个内置的机制来预览应用程序的电子邮件。实际上，这是将 basecamp/mail_view宝石移植到核心。

或者，还有其他一些宝石可以实现类似的功能，但采用了不同的方法和特点。例如：ryanb/letter_opener、sj26/mailcatcher 或 glebm/rails_email_preview。

开发

任何形式的反馈、错误报告、想法或改进都非常受欢迎 🎉

要贡献代码，只需派生仓库，进行修改并提交一个合并请求。别忘了为行为更改添加测试并运行测试套件：

> bundle exec rspec

针对所有支持的版本运行测试套件：

> bundle exec appraisal install
> bundle exec appraisal rspec

针对特定版本运行规格说明测试：

> bundle exec appraisal rails-6.0 rspec

示例

启动一个集成了 Maily 的示例 Rails 应用（源代码）。

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

许可证

版权所有（c）Marc Anguera。Maily 根据/MIT 许可证发布。