更多資訊請參考 rubyonrails.org:

Action Mailbox 基礎

本指南提供您開始在應用程式中接收電子郵件所需的一切。

閱讀本指南後，您將了解

  • 如何在 Rails 應用程式中接收電子郵件。
  • 如何設定 Action Mailbox。
  • 如何產生電子郵件並將其路由至信箱。
  • 如何測試收到的電子郵件。

1 什麼是 Action Mailbox？

Action Mailbox 將收到的電子郵件路由至類似控制器的信箱，以便在您的 Rails 應用程式中進行處理。Action Mailbox 用於接收電子郵件，而 Action Mailer 則用於傳送電子郵件。

收到的電子郵件會使用 Active Job 非同步地路由至一個或多個專用的信箱。這些電子郵件會使用 Active Record 轉換為 InboundEmail 記錄，這些記錄能夠直接與您的其他網域模型互動。

InboundEmail 記錄還提供生命週期追蹤、透過 Active Storage 儲存原始電子郵件，以及預設開啟 銷毀 的責任資料處理。

Action Mailbox 附帶入口，讓您的應用程式能夠從 Mailgun、Mandrill、Postmark 和 SendGrid 等外部電子郵件提供者接收電子郵件。您也可以透過內建的 Exim、Postfix 和 Qmail 入口直接處理收到的電子郵件。

2 設定

Action Mailbox 有一些運作的部分。首先，您需要執行安裝程式。接下來，您將選擇並設定一個入口來處理收到的電子郵件。然後，您就可以新增 Action Mailbox 路由、建立信箱，並開始處理收到的電子郵件。

首先，讓我們安裝 Action Mailbox

$ bin/rails action_mailbox:install

這會建立一個 application_mailbox.rb 檔案並複製遷移。

$ bin/rails db:migrate

這將執行 Action Mailbox 和 Active Storage 遷移。

Action Mailbox 表格 action_mailbox_inbound_emails 儲存收到的訊息及其處理狀態。

此時，您可以啟動您的 Rails 伺服器並查看 https://127.0.0.1:3000/rails/conductor/action_mailbox/inbound_emails。如需更多資訊，請參閱本機開發與測試。

下一步是在您的 Rails 應用程式中設定一個入口，以指定應如何接收收到的電子郵件。

3 入口設定

設定入口涉及為所選的電子郵件服務設定憑證和端點資訊。以下是每個支援入口的步驟。

3.1 Exim

告訴 Action Mailbox 接受來自 SMTP 中繼的電子郵件

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

產生一個強密碼，Action Mailbox 可以使用該密碼來驗證對中繼入口的請求。

使用 bin/rails credentials:edit 將密碼新增至您的應用程式的加密憑證中的 action_mailbox.ingress_password 下，Action Mailbox 會自動在此處找到該密碼

action_mailbox:
  ingress_password: ...

或者，在 RAILS_INBOUND_EMAIL_PASSWORD 環境變數中提供密碼。

設定 Exim 將收到的電子郵件管道傳送至 bin/rails action_mailbox:ingress:exim，提供中繼入口的 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 簽署金鑰（您可以在 Mailgun 的「設定」->「安全性與使用者」->「API 安全性」下找到），以便它可以驗證對 Mailgun 入口的請求。

使用 bin/rails credentials:edit 將您的簽署金鑰新增至您的應用程式的加密憑證中的 action_mailbox.mailgun_signing_key 下，Action Mailbox 會自動在此處找到該金鑰

action_mailbox:
  mailgun_signing_key: ...

或者，在 MAILGUN_INGRESS_SIGNING_KEY 環境變數中提供您的簽署金鑰。

告訴 Action Mailbox 接受來自 Mailgun 的電子郵件

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

設定 Mailgun 將收到的電子郵件轉寄至 /rails/action_mailbox/mailgun/inbound_emails/mime。如果您的應用程式位於 https://example.com，您將指定完整 URL https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime。

3.3 Mandrill

提供 Action Mailbox 您的 Mandrill API 金鑰，以便它可以驗證對 Mandrill 入口的請求。

使用 bin/rails credentials:edit 將您的 API 金鑰新增至您的應用程式的加密憑證中的 action_mailbox.mandrill_api_key 下，Action Mailbox 會自動在此處找到該金鑰

action_mailbox:
  mandrill_api_key: ...

或者，在 MANDRILL_INGRESS_API_KEY 環境變數中提供您的 API 金鑰。

告訴 Action Mailbox 接受來自 Mandrill 的電子郵件

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

設定 Mandrill 將收到的電子郵件路由至 /rails/action_mailbox/mandrill/inbound_emails。如果您的應用程式位於 https://example.com，您將指定完整 URL https://example.com/rails/action_mailbox/mandrill/inbound_emails。

3.4 Postfix

告訴 Action Mailbox 接受來自 SMTP 中繼的電子郵件

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

產生一個強密碼，Action Mailbox 可以使用該密碼來驗證對中繼入口的請求。

使用 bin/rails credentials:edit 將密碼新增至您的應用程式的加密憑證中的 action_mailbox.ingress_password 下，Action Mailbox 會自動在此處找到該密碼

action_mailbox:
  ingress_password: ...

或者，在 RAILS_INBOUND_EMAIL_PASSWORD 環境變數中提供密碼。

設定 Postfix 將收到的電子郵件管道傳送至 bin/rails action_mailbox:ingress:postfix，提供 Postfix 入口的 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

告訴 Action Mailbox 接受來自 Postmark 的電子郵件

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

產生一個強密碼，Action Mailbox 可以使用該密碼來驗證對 Postmark 入口的請求。

使用 bin/rails credentials:edit 將密碼新增至您的應用程式的加密憑證中的 action_mailbox.ingress_password 下，Action Mailbox 會自動在此處找到該密碼

action_mailbox:
  ingress_password: ...

或者，在 RAILS_INBOUND_EMAIL_PASSWORD 環境變數中提供密碼。

設定 Postmark 接收 Webhook 將收到的電子郵件轉寄至 /rails/action_mailbox/postmark/inbound_emails，使用者名稱為 actionmailbox，密碼為您先前產生的密碼。如果您的應用程式位於 https://example.com，您將使用以下完整 URL 設定 Postmark

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

設定 Postmark 接收 Webhook 時，請務必勾選標記為「在 JSON 酬載中包含原始電子郵件內容」的方塊。Action Mailbox 需要原始電子郵件內容才能運作。

3.6 Qmail

告訴 Action Mailbox 接受來自 SMTP 中繼的電子郵件

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

產生一個強密碼，Action Mailbox 可以使用該密碼來驗證對中繼入口的請求。

使用 bin/rails credentials:edit 將密碼新增至您的應用程式的加密憑證中的 action_mailbox.ingress_password 下，Action Mailbox 會自動在此處找到該密碼

action_mailbox:
  ingress_password: ...

或者，在 RAILS_INBOUND_EMAIL_PASSWORD 環境變數中提供密碼。

設定 Qmail 將收到的電子郵件管道傳送至 bin/rails action_mailbox:ingress:qmail，提供中繼入口的 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

告訴 Action Mailbox 接受來自 SendGrid 的電子郵件

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

產生一個強密碼，Action Mailbox 可以使用該密碼來驗證對 SendGrid 入口的請求。

使用 bin/rails credentials:edit 將密碼新增至您的應用程式的加密憑證中的 action_mailbox.ingress_password 下，Action Mailbox 會自動在此處找到該密碼

action_mailbox:
  ingress_password: ...

或者，在 RAILS_INBOUND_EMAIL_PASSWORD 環境變數中提供密碼。

設定 SendGrid 接收剖析將收到的電子郵件轉寄至 /rails/action_mailbox/sendgrid/inbound_emails，使用者名稱為 actionmailbox，密碼為您先前產生的密碼。如果您的應用程式位於 https://example.com，您將使用以下 URL 設定 SendGrid

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

當設定你的 SendGrid Inbound Parse webhook 時，請務必勾選標示為「Post the raw, full MIME message.」的核取方塊。Action Mailbox 需要原始的 MIME 訊息才能運作。

4 處理接收的電子郵件

處理接收的電子郵件通常需要在你的 Rails 應用程式中使用電子郵件內容來建立模型、更新視圖、將背景工作加入佇列等等。

在開始處理接收的電子郵件之前，你需要設定 Action Mailbox 路由並建立信箱。

4.1 設定路由

透過設定的入口接收到接收的電子郵件後，需要將其轉發到信箱以供應用程式實際處理。就像 Rails 路由器將 URL 分派給控制器一樣，Action Mailbox 中的路由定義哪些電子郵件會轉到哪個信箱進行處理。路由是使用正規表達式加入到 application_mailbox.rb 檔案中

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

正規表達式會比對接收電子郵件的 to、cc 或 bcc 欄位。例如，上面的範例會將任何發送到 save@ 的電子郵件比對到一個「forwards」信箱。還有其他路由電子郵件的方法，請參閱 ActionMailbox::Base 以了解更多資訊。

接下來我們需要建立該「forwards」信箱。

4.2 建立信箱

# Generate new mailbox
$ bin/rails generate mailbox forwards

這會在 app/mailboxes/forwards_mailbox.rb 中建立一個 ForwardsMailbox 類別和一個 process 方法。

4.3 處理電子郵件

在處理 InboundEmail 時，你可以使用 InboundEmail#mail 取得已解析為 Mail 物件的電子郵件版本。你也可以使用 #source 方法直接取得原始來源。透過 Mail 物件，你可以存取相關欄位，例如 mail.to、mail.body.decoded 等。

irb> mail
=> #<Mail::Message:33780, Multipart: false, Headers: <Date: Wed, 31 Jan 2024 22:18:40 -0600>, <From: someone@hey.com>, <To: save@example.com>, <Message-ID: <65bb1ba066830_50303a70397e@Bhumis-MacBook-Pro.local.mail>>, <In-Reply-To: >, <Subject: Hello Action Mailbox>, <Mime-Version: 1.0>, <Content-Type: text/plain; charset=UTF-8>, <Content-Transfer-Encoding: 7bit>, <x-original-to: >>
irb> mail.to
=> ["save@example.com"]
irb> mail.from
=> ["someone@hey.com"]
irb> mail.date
=> Wed, 31 Jan 2024 22:18:40 -0600
irb> mail.subject
=> "Hello Action Mailbox"
irb> mail.body.decoded
=> "This is the body of the email message."
# mail.decoded, a shorthand for mail.body.decoded, also works
irb> mail.decoded
=> "This is the body of the email message."
irb> mail.body
=> <Mail::Body:0x00007fc74cbf46c0 @boundary=nil, @preamble=nil, @epilogue=nil, @charset="US-ASCII", @part_sort_order=["text/plain", "text/enriched", "text/html", "multipart/alternative"], @parts=[], @raw_source="This is the body of the email message.", @ascii_only=true, @encoding="7bit">

4.4 接收的電子郵件狀態

當電子郵件被路由到相符的信箱並進行處理時，Action Mailbox 會使用下列其中一個值更新儲存在 action_mailbox_inbound_emails 表格中的電子郵件狀態

  • pending：由其中一個入口控制器接收，並已排程進行路由。
  • processing：在特定信箱執行其 process 方法時的活動處理期間。
  • delivered：由特定信箱成功處理。
  • failed：在特定信箱執行 process 方法時引發了例外狀況。
  • bounced：遭特定信箱拒絕處理並退回給寄件人。

如果電子郵件被標記為 delivered、failed 或 bounced，則視為「已處理」並標記為 銷毀。

5 範例

以下是一個 Action Mailbox 的範例，它會處理電子郵件，為使用者的專案建立「轉寄」。

before_processing 回呼用於確保在呼叫 process 方法之前滿足某些條件。在此範例中，before_processing 會檢查使用者是否至少有一個專案。其他支援的 Action Mailbox 回呼 有 after_processing 和 around_processing。

如果「轉寄者」沒有專案，則可以使用 bounced_with 退回電子郵件。「轉寄者」是與 mail.from 具有相同電子郵件的 User。

如果「轉寄者」至少有一個專案，record_forward 方法會使用電子郵件資料 mail.subject 和 mail.decoded 在應用程式中建立一個 Active Record 模型。否則，它會使用 Action Mailer 發送電子郵件，要求「轉寄者」選擇一個專案。

# app/mailboxes/forwards_mailbox.rb
class ForwardsMailbox < ApplicationMailbox
  # Callbacks specify prerequisites to processing
  before_processing :require_projects

  def process
    # Record the forward on the one project, or…
    if forwarder.projects.one?
      record_forward
    else
      # …involve a second Action Mailer to ask which project to forward into.
      request_forwarding_project
    end
  end

  private
    def require_projects
      if forwarder.projects.none?
        # Use Action Mailers to bounce incoming emails back to sender – this halts processing
        bounce_with Forwards::BounceMailer.no_projects(inbound_email, forwarder: forwarder)
      end
    end

    def record_forward
      forwarder.forwards.create subject: mail.subject, content: mail.decoded
    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

6 本機開發和測試

能夠在開發過程中測試接收的電子郵件，而無需實際發送和接收真實的電子郵件會很有幫助。為了實現這一點，在 /rails/conductor/action_mailbox/inbound_emails 上掛載了一個導線控制器，它會提供系統中所有 InboundEmails 的索引、它們的處理狀態，以及一個建立新 InboundEmail 的表單。

以下是使用 Action Mailbox TestHelpers 測試接收電子郵件的範例。

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: Status update?",
        body: <<~BODY
          --- Begin forwarded message ---
          From: Frank Holland <frank@microsoft.com>

          What's the status?
        BODY
    end

    recording = people(:david).buckets.first.recordings.last
    assert_equal people(:david), recording.creator
    assert_equal "Status update?", recording.forward.subject
    assert_match "What's the status?", recording.forward.content.to_s
  end
end

請參閱 ActionMailbox::TestHelper API 以了解更多測試協助方法。

7 銷毀 InboundEmails

依預設，已處理的 InboundEmail 將在 30 天後銷毀。當 InboundEmail 的狀態變更為 delivered、failed 或 bounced 時，會被視為已處理。

實際的銷毀是透過在 config.action_mailbox.incinerate_after 時間後排程執行的 IncinerationJob 完成。此值預設設定為 30.days，但你可以在 production.rb 設定中變更它。（請注意，這種遠期銷毀排程依賴你的工作佇列能夠長時間保留工作。）

預設的資料銷毀可確保你在人們取消帳戶或刪除內容後，不會不必要地保留他們資料。

使用 Action Mailbox 處理的目的是，當你處理電子郵件時，應從電子郵件中提取你需要的所有資料，並將其持久化到應用程式中的網域模型中。InboundEmail 會在系統中保留設定的時間，以便進行偵錯和鑑識，然後將會被刪除。

回到頂端