Action Mailbox の基礎

本ガイドでは、アプリケーションでメールを受信するために必要なすべての情報を提供します。

このガイドの内容:

メールをRailsアプリケーションで受信する方法
Action Mailboxの設定方法
メールボックスの生成方法とメールをメールボックスにルーティングする方法
受信メールをテストする方法

1 はじめに

Action Mailboxは、受信したメールをコントローラに似たメールボックスにルーティングし、Railsで処理できるようにします。Action Mailboxは、Mailgun、Mandrill、Postmark、SendGridへの入り口（ingress）を備えています。受信メールを組み込みのEximやPostfixやQmail用のingressで直接扱うこともできます。

受信メールはActive Recordを用いてInboundEmailレコードになり、Active Storageによってライフサイクルトラッキングや元のメールのクラウドストレージ保存を行い、データを「on-by-default incineration（焼却）」で責任を持って扱います。

受信メールはActive Jobによって非同期的に1つまたは複数の専用メールボックスにルーティングされ、ドメインモデルの他の部分と直接やりとりできます。

2 セットアップ

以下を実行してInboundEmailで必要となるマイグレーションをインストールし、Active Storageがセットアップ済みであることを確認します。

$ bin/rails action_mailbox:install
$ bin/rails db:migrate

3 設定

3.1 Exim

SMTPリレーからのメールを受け取るようAction Mailboxに指示します。

# config/environments/production.rb
config.action_mailbox.ingress = :relay

Action Mailboxがrelay ingressへのリクエストを認証するのに使える強力なパスワードを生成します。

パスワードを追加するにはbin/rails credentials:editを実行します。パスワードはアプリケーションの暗号化済みcredentialのaction_mailbox.ingress_passwordの下に追加されます（Action Mailboxはこのcredentialを自動的に見つけます）。

action_mailbox:
  ingress_password: ...

または、RAILS_INBOUND_EMAIL_PASSWORD環境変数でパスワードを指定します。

Eximを設定して受信メールをbin/rails action_mailbox:ingress:eximにパイプでつなぎ、relay ingressのURLと先ほど生成したINGRESS_PASSWORDを指定します。アプリケーションがhttps://example.comにある場合の完全なコマンドは以下のような感じになります。

bin/rails action_mailbox:ingress:exim URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...

3.2 Mailgun

Action Mailboxに自分のMailgun署名キー（Signing key）を渡して、Mailgun ingressへのリクエストを認証できるようにします。

bin/rails credentials:editを実行して署名キーを追加します。署名キーはアプリケーションの暗号化済みcredentialのaction_mailbox.mailgun_signing_keyの下に追加されます（Action Mailboxはこのcredentialを自動的に見つけます）。

action_mailbox:
  mailgun_api_key: ...

または、MAILGUN_INGRESS_SIGNING_KEY環境変数でパスワードを指定します。

Mailgunからのメールを受け取るようAction Mailboxに指示します。

# config/environments/production.rb
config.action_mailbox.ingress = :mailgun

受信メールを/rails/action_mailbox/mailgun/inbound_emails/mimeに転送するようMailgunを設定します。たとえばアプリケーションがhttps://example.comにある場合は、完全修飾済みURLをhttps://example.com/rails/action_mailbox/mailgun/inbound_emails/mimeのように指定します。

3.3 Mandrill

Action Mailboxに自分のMandrill APIキーを渡して、Mandrillのingressへのリクエストを認証できるようにします。

bin/rails credentials:editを実行してAPIキーを追加します。APIキーはアプリケーションの暗号化済みcredentialのaction_mailbox.mandrill_api_keyの下に追加されます（Action Mailboxはこのcredentialを自動的に見つけます）。

action_mailbox:
  mandrill_api_key: ...

または、MANDRILL_INGRESS_API_KEY環境変数でパスワードを指定します。

Mandrillからのメールを受け取るようAction Mailboxに指示します。

# config/environments/production.rb
config.action_mailbox.ingress = :mandrill

受信メールを/rails/action_mailbox/mandrill/inbound_emailsにルーティングするようMandrillを設定します。アプリケーションがhttps://example.comにある場合、完全修飾済みURLをhttps://example.com/rails/action_mailbox/mandrill/inbound_emailsのように指定します。

3.4 Postfix

SMTPリレーからのメールを受け取るようAction Mailboxに指示します。

# config/environments/production.rb
config.action_mailbox.ingress = :relay

Action Mailboxがrelay ingressへのリクエストを認証するのに使える強力なパスワードを生成します。

bin/rails credentials:editを実行してAPIキーを追加します。APIキーはアプリケーションの暗号化済みcredentialのaction_mailbox.ingress_passwordの下に追加されます（Action Mailboxはこのcredentialを自動的に見つけます）。

action_mailbox:
  ingress_password: ...

または、RAILS_INBOUND_EMAIL_PASSWORD環境変数でパスワードを指定します。

受信メールをbin/rails action_mailbox:ingress:postfixにルーティングするようPostfixを設定し、Postfix ingressのURLと先ほど生成したINGRESS_PASSWORDを指定します。アプリケーションがhttps://example.comにある場合の完全なコマンドは以下のようになります。

$ bin/rails action_mailbox:ingress:postfix URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...

3.5 Postmark

Postmarkからのメールを受け取るようAction Mailboxに指示します。

# config/environments/production.rb
config.action_mailbox.ingress = :postmark

Action MailboxがPostmarkのingressへのリクエストを認証するのに使える強力なパスワードを生成します。

action_mailbox:
  ingress_password: ...

または、RAILS_INBOUND_EMAIL_PASSWORD環境変数でパスワードを指定します。

受信メールを/rails/action_mailbox/postmark/inbound_emailsに転送するようPostmarkのinbound webhookを設定し、ユーザー名actionmailboxと上で生成したパスワードを指定します。アプリケーションがhttps://example.comにある場合の完全なコマンドは以下のようになります。

https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/postmark/inbound_emails

Postmarkのinbound webhookを設定するときには、必ず"Include raw email content in JSON payload"というチェックボックスをオンにしてください。これはAction Mailboxがメールのrawコンテンツを処理するのに必要です。

3.6 Qmail

SMTPリレーからのメールを受け取るようAction Mailboxに指示します。

# config/environments/production.rb
config.action_mailbox.ingress = :relay

Action Mailboxがrelay ingressへのリクエストを認証するのに使える強力なパスワードを生成します。

action_mailbox:
  ingress_password: ...

または、RAILS_INBOUND_EMAIL_PASSWORD環境変数でパスワードを指定します。

受信メールをbin/rails action_mailbox:ingress:qmailにパイプでつなぐようQmailを設定し、relay ingressのURLと先ほど生成したINGRESS_PASSWORDを指定します。アプリケーションがhttps://example.comにある場合の完全なコマンドは以下のようになります。

bin/rails action_mailbox:ingress:qmail URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...

3.7 SendGrid

SendGridからのメールを受け取るようAction Mailboxに指示します。

# config/environments/production.rb
config.action_mailbox.ingress = :sendgrid

Action MailboxがSendGridのingressへのリクエストを認証するのに使える強力なパスワードを生成します。

action_mailbox:
  ingress_password: ...

または、RAILS_INBOUND_EMAIL_PASSWORD環境変数でパスワードを指定します。

受信メールを/rails/action_mailbox/sendgrid/inbound_emailsに転送するようSendGridのInbound Parseを設定し、ユーザー名actionmailboxと上で生成したパスワードを指定します。アプリケーションがhttps://example.comにある場合、SendGridの設定に使うURLは次のような感じになります。

https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails

SendGridのInbound Parse webhookを設定するときには、必ず“Post the raw, full MIME message”というチェックボックスをオンにしてください。これはAction Mailboxがraw MIMEメッセージを処理するのに必要です。

4 例

基本的なルーティングを設定します。

# app/mailboxes/application_mailbox.rb
class ApplicationMailbox < ActionMailbox::Base
  routing(/^save@/i     => :forwards)
  routing(/@replies\./i => :replies)
end

続いてメールボックスを設定します。

# 新しいメールボックスを生成する
$ bin/rails generate mailbox forwards

# app/mailboxes/forwards_mailbox.rb
class ForwardsMailbox < ApplicationMailbox
  # 処理に必要な条件をコールバックで指定する
  before_processing :require_projects

  def process
    # 転送を1個のプロジェクトに記録する、または…
    if forwarder.projects.one?
      record_forward
    else
      # …2番目のAction Mailerに転送先プロジェクトを問い合わせてもらう
      request_forwarding_project
    end
  end

  private
    def require_projects
      if forwarder.projects.none?
        # Action Mailersを用いて受信メールを送信者に送り返す（bounce back）
        # ここで処理が停止する
        bounce_with Forwards::BounceMailer.no_projects(inbound_email, forwarder: forwarder)
      end
    end

    def record_forward
      forwarder.forwards.create subject: mail.subject, content: mail.content
    end

    def request_forwarding_project
      Forwards::RoutingMailer.choose_project(inbound_email, forwarder: forwarder).deliver_now
    end

    def forwarder
      @forwarder ||= User.find_by(email_address: mail.from)
    end
end

5 InboundEmailsの「焼却」

デフォルトでは、処理が成功したInboundEmailは30日後に焼却（incinerate）されます。これにより、アカウントをキャンセルまたはコンテンツを削除したユーザーのデータをむやみに保持せずに済みます。この設計では、メールを処理した後に必要なメールをすべて切り出して、アプリケーションの業務ドメインモデルやコンテンツに取り込む必要があることが前提となります。InboundEmailがシステムに余分に保持される期間は、単にデバッグや事後調査のためのものです。

実際のincinerationは、config.action_mailbox.incinerate_afterでスケジュールされた時刻の後、IncinerationJobで行われます。この値はデフォルトで30.daysに設定されますが、production.rbで設定を変更できます（incinerationを遠い未来にスケジューリングする場合、その間ジョブキューがジョブを保持可能になっていることが重要です）。

6 Action Mailboxをdevelopment環境で使う

実際にメールを送受信せずに、development環境でメールの受信をテストできると便利です。このために、/rails/conductor/action_mailbox/inbound_emailsにコンダクター（conductor）コントローラがマウントされます。コンダクターコントローラは、システム内にあるすべてのInboundEmailsのインデックスや処理のステートを提供し、新しいInboundEmailを作成するときのフォームも提供します。

7 メールボックスをテストする

例:

class ForwardsMailboxTest < ActionMailbox::TestCase
  test "directly recording a client forward for a forwarder and forwardee corresponding to one project" do
    assert_difference -> { people(:david).buckets.first.recordings.count } do
      receive_inbound_email_from_mail \
        to: 'save@example.com',
        from: people(:david).email_address,
        subject: "Fwd: ステータスは更新されたか？",
        body: <<~BODY
          --- Begin forwarded message ---
          From: Frank Holland <frank@microsoft.com>

          現在のステータスは？
        BODY
    end

    recording = people(:david).buckets.first.recordings.last
    assert_equal people(:david), recording.creator
    assert_equal "ステータスは更新されたか？", recording.forward.subject
    assert_match "現在のステータスは？", recording.forward.content.to_s
  end
end

テストヘルパーメソッドについて詳しくは、ActionMailbox::TestHelper APIドキュメントを参照してください。

🖋 GitHubで編集を提案する / 📕 英語で読む

フィードバックについて

Railsガイドは GitHub の yasslab/railsguides.jp で管理・公開されております。本ガイドを読んで気になる文章や間違ったコードを見かけたら、気軽に Pull Request を出して頂けると嬉しいです。Pull Request の送り方については GitHub の README をご参照ください。

原著における間違いを見つけたら『Rails のドキュメントに貢献する』を参考にしながらぜひ Rails コミュニティに貢献してみてください 🛠💨✨

本ガイドの品質向上に向けて、皆さまのご協力が得られれば嬉しいです。

Railsガイド運営チーム (@RailsGuidesJP)

支援・協賛

Railsガイドは下記の協賛企業から継続的な支援を受けています。支援・協賛にご興味あれば協賛プランからお問い合わせいただけると嬉しいです。

Star

/ 検索を開始	ctrl + p 前の検索項目	↑ 前の検索項目
esc フォーカスを解除	ctrl + n 次の検索項目	↓ 次の検索項目
cmd + f ページ内検索 (ブラウザ標準)	? ヘルプの表示

Rails ガイド

Keybord Shortcuts