10 files changed, 109 insertions, 41 deletions
diff --git a/actionmailbox/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb b/actionmailbox/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb
index cf45ac8408..e0a187054e 100644
--- a/actionmailbox/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb
+++ b/actionmailbox/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb
@@ -37,7 +37,7 @@ module ActionMailbox
 
     def self.prepare
       self.verifier ||= begin
-        require "aws-sdk-sns/message_verifier"
+        require "aws-sdk-sns"
         Aws::SNS::MessageVerifier.new
       end
     end
diff --git a/actionmailbox/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb b/actionmailbox/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb
index ebe83a9ec0..bf0fd562fe 100644
--- a/actionmailbox/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb
+++ b/actionmailbox/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb
@@ -38,7 +38,7 @@ module ActionMailbox
   #        config.action_mailbox.ingress = :mailgun
   #
   # 3. {Configure Mailgun}[https://documentation.mailgun.com/en/latest/user_manual.html#receiving-forwarding-and-storing-messages]
-  #    to forward inbound emails to `/rails/action_mailbox/mailgun/inbound_emails/mime`.
+  #    to forward inbound emails to +/rails/action_mailbox/mailgun/inbound_emails/mime+.
   #
   #    If your application lived at <tt>https://example.com</tt>, you would specify the fully-qualified URL
   #    <tt>https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime</tt>.
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..309085c82a
--- /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 a +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}[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 your
+  #    Postmark inbound webhook 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/app/controllers/action_mailbox/ingresses/postfix/inbound_emails_controller.rb b/actionmailbox/app/controllers/action_mailbox/ingresses/relay/inbound_emails_controller.rb
index c0d5002a12..2d91c968c8 100644
--- a/actionmailbox/app/controllers/action_mailbox/ingresses/postfix/inbound_emails_controller.rb
+++ b/actionmailbox/app/controllers/action_mailbox/ingresses/relay/inbound_emails_controller.rb
@@ -1,31 +1,31 @@
 # frozen_string_literal: true
 
 module ActionMailbox
-  # Ingests inbound emails relayed from Postfix.
+  # Ingests inbound emails relayed from an SMTP server.
   #
   # 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 Postfix ingress can learn its password. You should only use the Postfix ingress over HTTPS.
+  # the ingress can learn its password. You should only use this 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 could not be authenticated
-  # - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from Postfix
+  # - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails relayed from an SMTP server
   # - <tt>415 Unsupported Media Type</tt> if the request does not contain an RFC 822 message
   # - <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 Postfix:
+  # 1. Tell Action Mailbox to accept emails from an SMTP relay:
   #
   #        # config/environments/production.rb
-  #        config.action_mailbox.ingress = :postfix
+  #        config.action_mailbox.ingress = :relay
   #
-  # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the Postfix ingress.
+  # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the 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:
@@ -35,14 +35,20 @@ module ActionMailbox
   #
   #    Alternatively, provide the password in the +RAILS_INBOUND_EMAIL_PASSWORD+ environment variable.
   #
-  # 3. {Configure Postfix}[https://serverfault.com/questions/258469/how-to-configure-postfix-to-pipe-all-incoming-email-to-a-script]
-  #    to pipe inbound emails to <tt>bin/rails action_mailbox:ingress:postfix</tt>, providing the +URL+ of the Postfix
-  #    ingress and the +INGRESS_PASSWORD+ you previously generated.
+  # 3. Configure your SMTP server to pipe inbound emails to the appropriate ingress command, providing the +URL+ of the
+  #    relay ingress and the +INGRESS_PASSWORD+ you previously generated.
   #
-  #    If your application lived at <tt>https://example.com</tt>, the full command would look like this:
+  #    If your application lives at <tt>https://example.com</tt>, you would configure the Postfix SMTP server to pipe
+  #    inbound emails to the following command:
   #
-  #        URL=https://example.com/rails/action_mailbox/postfix/inbound_emails INGRESS_PASSWORD=... bin/rails action_mailbox:ingress:postfix
-  class Ingresses::Postfix::InboundEmailsController < ActionMailbox::BaseController
+  #        bin/rails action_mailbox:ingress:postfix URL=https://example.com/rails/action_mailbox/postfix/inbound_emails INGRESS_PASSWORD=...
+  #
+  #    Built-in ingress commands are available for these popular SMTP servers:
+  #
+  #    - Exim (<tt>bin/rails action_mailbox:ingress:exim)
+  #    - Postfix (<tt>bin/rails action_mailbox:ingress:postfix)
+  #    - Qmail (<tt>bin/rails action_mailbox:ingress:qmail)
+  class Ingresses::Relay::InboundEmailsController < ActionMailbox::BaseController
     before_action :authenticate_by_password, :require_valid_rfc822_message
 
     def create
diff --git a/actionmailbox/app/jobs/action_mailbox/incineration_job.rb b/actionmailbox/app/jobs/action_mailbox/incineration_job.rb
index 224c9329a5..1579a3c7c8 100644
--- a/actionmailbox/app/jobs/action_mailbox/incineration_job.rb
+++ b/actionmailbox/app/jobs/action_mailbox/incineration_job.rb
@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module ActionMailbox
-  # You can configure when this `IncinerationJob` will be run as a time-after-processing using the
-  # `config.action_mailbox.incinerate_after` or `ActionMailbox.incinerate_after` setting.
+  # You can configure when this +IncinerationJob+ will be run as a time-after-processing using the
+  # +config.action_mailbox.incinerate_after+ or +ActionMailbox.incinerate_after+ setting.
   #
-  # Since this incineration is set for the future, it'll automatically ignore any `InboundEmail`s
+  # Since this incineration is set for the future, it'll automatically ignore any <tt>InboundEmail</tt>s
   # that have already been deleted and discard itself if so.
   class IncinerationJob < ActiveJob::Base
     queue_as { ActionMailbox.queues[:incineration] }
diff --git a/actionmailbox/app/models/action_mailbox/inbound_email.rb b/actionmailbox/app/models/action_mailbox/inbound_email.rb
index 3a8dfd163c..023de19ccc 100644
--- a/actionmailbox/app/models/action_mailbox/inbound_email.rb
+++ b/actionmailbox/app/models/action_mailbox/inbound_email.rb
@@ -3,22 +3,22 @@
 require "mail"
 
 module ActionMailbox
-  # The `InboundEmail` is an Active Record that keeps a reference to the raw email stored in Active Storage
+  # The +InboundEmail+ is an Active Record that keeps a reference to the raw email stored in Active Storage
   # and tracks the status of processing. By default, incoming emails will go through the following lifecycle:
   #
   # * Pending: Just received by one of the ingress controllers and scheduled for routing.
   # * Processing: During active processing, while a specific mailbox is running its #process method.
   # * Delivered: Successfully processed by the specific mailbox.
-  # * Failed: An exception was raised during the specific mailbox's execution of the `#process` method.
+  # * Failed: An exception was raised during the specific mailbox's execution of the +#process+ method.
   # * Bounced: Rejected processing by the specific mailbox and bounced to sender.
   #
-  # Once the `InboundEmail` has reached the status of being either `delivered`, `failed`, or `bounced`,
-  # it'll count as having been `#processed?`. Once processed, the `InboundEmail` will be scheduled for
+  # Once the +InboundEmail+ has reached the status of being either +delivered+, +failed+, or +bounced+,
+  # it'll count as having been +#processed?+. Once processed, the +InboundEmail+ will be scheduled for
   # automatic incineration at a later point.
   #
-  # When working with an `InboundEmail`, you'll usually interact with the parsed version of the source,
-  # which is available as a `Mail` object from `#mail`. But you can also access the raw source directly
-  # using the `#source` method.
+  # When working with an +InboundEmail+, you'll usually interact with the parsed version of the source,
+  # which is available as a +Mail+ object from +#mail+. But you can also access the raw source directly
+  # using the +#source+ method.
   #
   # Examples:
   #
diff --git a/actionmailbox/app/models/action_mailbox/inbound_email/incineratable.rb b/actionmailbox/app/models/action_mailbox/inbound_email/incineratable.rb
index 825e300648..697331ede4 100644
--- a/actionmailbox/app/models/action_mailbox/inbound_email/incineratable.rb
+++ b/actionmailbox/app/models/action_mailbox/inbound_email/incineratable.rb
@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-# Ensure that the `InboundEmail` is automatically scheduled for later incineration if the status has been
-# changed to `processed`. The later incineration will be invoked at the time specified by the
-# `ActionMailbox.incinerate_after` time using the `IncinerationJob`.
+# Ensure that the +InboundEmail+ is automatically scheduled for later incineration if the status has been
+# changed to +processed+. The later incineration will be invoked at the time specified by the
+# +ActionMailbox.incinerate_after+ time using the +IncinerationJob+.
 module ActionMailbox::InboundEmail::Incineratable
   extend ActiveSupport::Concern
 
diff --git a/actionmailbox/app/models/action_mailbox/inbound_email/incineratable/incineration.rb b/actionmailbox/app/models/action_mailbox/inbound_email/incineratable/incineration.rb
index 685f7fceb6..dabc83fae6 100644
--- a/actionmailbox/app/models/action_mailbox/inbound_email/incineratable/incineration.rb
+++ b/actionmailbox/app/models/action_mailbox/inbound_email/incineratable/incineration.rb
@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module ActionMailbox
-  # Command class for carrying out the actual incineration of the `InboundMail` that's been scheduled
-  # for removal. Before the incineration – which really is just a call to `#destroy!` – is run, we verify
+  # Command class for carrying out the actual incineration of the +InboundMail+ that's been scheduled
+  # for removal. Before the incineration – which really is just a call to +#destroy!+ – is run, we verify
   # that it's both eligible (by virtue of having already been processed) and time to do so (that is,
-  # the `InboundEmail` was processed after the `incinerate_after` time).
+  # the +InboundEmail+ was processed after the +incinerate_after+ time).
   class InboundEmail::Incineratable::Incineration
     def initialize(inbound_email)
       @inbound_email = inbound_email
diff --git a/actionmailbox/app/models/action_mailbox/inbound_email/message_id.rb b/actionmailbox/app/models/action_mailbox/inbound_email/message_id.rb
index 2ad4525929..57b4a2445d 100644
--- a/actionmailbox/app/models/action_mailbox/inbound_email/message_id.rb
+++ b/actionmailbox/app/models/action_mailbox/inbound_email/message_id.rb
@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-# The `Message-ID` as specified by rfc822 is supposed to be a unique identifier for that individual email.
-# That makes it an ideal tracking token for debugging and forensics, just like `X-Request-Id` does for
+# The +Message-ID+ as specified by rfc822 is supposed to be a unique identifier for that individual email.
+# That makes it an ideal tracking token for debugging and forensics, just like +X-Request-Id+ does for
 # web request.
 #
 # If an inbound email does not, against the rfc822 mandate, specify a Message-ID, one will be generated
-# using the approach from `Mail::MessageIdField`.
+# using the approach from <tt>Mail::MessageIdField</tt>.
 module ActionMailbox::InboundEmail::MessageId
   extend ActiveSupport::Concern
 
@@ -14,9 +14,9 @@ module ActionMailbox::InboundEmail::MessageId
   end
 
   class_methods do
-    # Create a new `InboundEmail` from the raw `source` of the email, which be uploaded as a Active Storage
-    # attachment called `raw_email`. Before the upload, extract the Message-ID from the `source` and set
-    # it as an attribute on the new `InboundEmail`.
+    # Create a new +InboundEmail+ from the raw +source+ of the email, which be uploaded as a Active Storage
+    # attachment called +raw_email+. Before the upload, extract the Message-ID from the +source+ and set
+    # it as an attribute on the new +InboundEmail+.
     def create_and_extract_message_id!(source, **options)
       create! options.merge(message_id: extract_message_id(source)) do |inbound_email|
         inbound_email.raw_email.attach io: StringIO.new(source), filename: "message.eml", content_type: "message/rfc822"
diff --git a/actionmailbox/app/models/action_mailbox/inbound_email/routable.rb b/actionmailbox/app/models/action_mailbox/inbound_email/routable.rb
index 58d67eb20c..39565df166 100644
--- a/actionmailbox/app/models/action_mailbox/inbound_email/routable.rb
+++ b/actionmailbox/app/models/action_mailbox/inbound_email/routable.rb
@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-# A newly received `InboundEmail` will not be routed synchronously as part of ingress controller's receival.
-# Instead, the routing will be done asynchronously, using a `RoutingJob`, to ensure maximum parallel capacity.
+# A newly received +InboundEmail+ will not be routed synchronously as part of ingress controller's receival.
+# Instead, the routing will be done asynchronously, using a +RoutingJob+, to ensure maximum parallel capacity.
 #
-# By default, all newly created `InboundEmail` records that have the status of `pending`, which is the default,
+# By default, all newly created +InboundEmail+ records that have the status of +pending+, which is the default,
 # will be scheduled for automatic, deferred routing.
 module ActionMailbox::InboundEmail::Routable
   extend ActiveSupport::Concern
@@ -12,12 +12,12 @@ module ActionMailbox::InboundEmail::Routable
     after_create_commit :route_later, if: :pending?
   end
 
-  # Enqueue a `RoutingJob` for this `InboundEmail`.
+  # Enqueue a +RoutingJob+ for this +InboundEmail+.
   def route_later
     ActionMailbox::RoutingJob.perform_later self
   end
 
-  # Route this `InboundEmail` using the routing rules declared on the `ApplicationMailbox`.
+  # Route this +InboundEmail+ using the routing rules declared on the +ApplicationMailbox+.
   def route
     ApplicationMailbox.route self
   end