Merge pull request #34907 from wildbit/actionmailbox-postmark

Add Postmark ingress support to ActionMailbox

3 files changed, 118 insertions, 0 deletions

diff --git a/actionmailbox/app/controllers/action_mailbox/ingresses/postmark/inbound_emails_controller.rb b/actionmailbox/app/controllers/action_mailbox/ingresses/postmark/inbound_emails_controller.rb
new file mode 100644
index 0000000000..ec4e0da5ec
--- /dev/null
+++ b/actionmailbox/app/controllers/action_mailbox/ingresses/postmark/inbound_emails_controller.rb
@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # Ingests inbound emails from Postmark. Requires +RawEmail+ parameter containing a full RFC 822 message.
+  #
+  # Authenticates requests using HTTP basic access authentication. The username is always +actionmailbox+, and the
+  # password is read from the application's encrypted credentials or an environment variable. See the Usage section below.
+  #
+  # Note that basic authentication is insecure over unencrypted HTTP. An attacker that intercepts cleartext requests to
+  # the Postmark ingress can learn its password. You should only use the Postmark ingress over HTTPS.
+  #
+  # Returns:
+  #
+  # - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for routing to the appropriate mailbox
+  # - <tt>401 Unauthorized</tt> if the request's signature could not be validated
+  # - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from Postmark
+  # - <tt>422 Unprocessable Entity</tt> if the request is missing the required +RawEmail+ parameter
+  # - <tt>500 Server Error</tt> if the ingress password is not configured, or if one of the Active Record database,
+  #   the Active Storage service, or the Active Job backend is misconfigured or unavailable
+  #
+  # == Usage
+  #
+  # 1. Tell Action Mailbox to accept emails from Postmark:
+  #
+  #        # config/environments/production.rb
+  #        config.action_mailbox.ingress = :postmark
+  #
+  # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the Postmark ingress.
+  #
+  #    Use <tt>rails credentials:edit</tt> to add the password to your application's encrypted credentials under
+  #    +action_mailbox.ingress_password+, where Action Mailbox will automatically find it:
+  #
+  #        action_mailbox:
+  #          ingress_password: ...
+  #
+  #    Alternatively, provide the password in the +RAILS_INBOUND_EMAIL_PASSWORD+ environment variable.
+  #
+  # 3. {Configure Postmark inbound webhook}[https://postmarkapp.com/manual#configure-your-inbound-webhook-url]
+  #    to forward inbound emails to +/rails/action_mailbox/postmark/inbound_emails+ with the username +actionmailbox+ and
+  #    the password you previously generated. If your application lived at <tt>https://example.com</tt>, you would
+  #    configure Postmark with the following fully-qualified URL:
+  #
+  #        https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/postmark/inbound_emails
+  #
+  #    *NOTE:* When configuring your Postmark inbound webhook, be sure to check the box labeled *"Include raw email
+  #    content in JSON payload"*. Action Mailbox needs the raw email content to work.
+  class Ingresses::Postmark::InboundEmailsController < ActionMailbox::BaseController
+    before_action :authenticate_by_password
+
+    def create
+      ActionMailbox::InboundEmail.create_and_extract_message_id! params.require("RawEmail")
+    rescue ActionController::ParameterMissing => error
+      logger.error <<~MESSAGE
+        #{error.message}
+
+        When configuring your Postmark inbound webhook, be sure to check the box
+        labeled "Include raw email content in JSON payload".
+      MESSAGE
+      head :unprocessable_entity
+    end
+  end
+end
diff --git a/actionmailbox/config/routes.rb b/actionmailbox/config/routes.rb
index f1bc9847f5..7aa230fdff 100644
--- a/actionmailbox/config/routes.rb
+++ b/actionmailbox/config/routes.rb
@@ -5,6 +5,7 @@ Rails.application.routes.draw do
     post "/amazon/inbound_emails"   => "amazon/inbound_emails#create",   as: :rails_amazon_inbound_emails
     post "/mandrill/inbound_emails" => "mandrill/inbound_emails#create", as: :rails_mandrill_inbound_emails
     post "/postfix/inbound_emails"  => "postfix/inbound_emails#create",  as: :rails_postfix_inbound_emails
+    post "/postmark/inbound_emails" => "postmark/inbound_emails#create", as: :rails_postmark_inbound_emails
     post "/sendgrid/inbound_emails" => "sendgrid/inbound_emails#create", as: :rails_sendgrid_inbound_emails
 
     # Mailgun requires that a webhook's URL end in 'mime' for it to receive the raw contents of emails.
diff --git a/actionmailbox/test/controllers/ingresses/postmark/inbound_emails_controller_test.rb b/actionmailbox/test/controllers/ingresses/postmark/inbound_emails_controller_test.rb
new file mode 100644
index 0000000000..11b579b39c
--- /dev/null
+++ b/actionmailbox/test/controllers/ingresses/postmark/inbound_emails_controller_test.rb
@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ActionMailbox::Ingresses::Postmark::InboundEmailsControllerTest < ActionDispatch::IntegrationTest
+  setup { ActionMailbox.ingress = :postmark }
+
+  test "receiving an inbound email from Postmark" do
+    assert_difference -> { ActionMailbox::InboundEmail.count }, +1 do
+      post rails_postmark_inbound_emails_url,
+        headers: { authorization: credentials }, params: { RawEmail: file_fixture("../files/welcome.eml").read }
+    end
+
+    assert_response :no_content
+
+    inbound_email = ActionMailbox::InboundEmail.last
+    assert_equal file_fixture("../files/welcome.eml").read, inbound_email.raw_email.download
+    assert_equal "0CB459E0-0336-41DA-BC88-E6E28C697DDB@37signals.com", inbound_email.message_id
+  end
+
+  test "rejecting when RawEmail param is missing" do
+    assert_no_difference -> { ActionMailbox::InboundEmail.count } do
+      post rails_postmark_inbound_emails_url,
+        headers: { authorization: credentials }, params: { From: "someone@example.com" }
+    end
+
+    assert_response :unprocessable_entity
+  end
+
+  test "rejecting an unauthorized inbound email from Postmark" do
+    assert_no_difference -> { ActionMailbox::InboundEmail.count } do
+      post rails_postmark_inbound_emails_url, params: { RawEmail: file_fixture("../files/welcome.eml").read }
+    end
+
+    assert_response :unauthorized
+  end
+
+  test "raising when the configured password is nil" do
+    switch_password_to nil do
+      assert_raises ArgumentError do
+        post rails_postmark_inbound_emails_url,
+          headers: { authorization: credentials }, params: { RawEmail: file_fixture("../files/welcome.eml").read }
+      end
+    end
+  end
+
+  test "raising when the configured password is blank" do
+    switch_password_to "" do
+      assert_raises ArgumentError do
+        post rails_postmark_inbound_emails_url,
+          headers: { authorization: credentials }, params: { RawEmail: file_fixture("../files/welcome.eml").read }
+      end
+    end
+  end
+end