Nest Action Mailbox classes in the API docs

1 files changed, 49 insertions, 47 deletions

diff --git a/actionmailbox/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb b/actionmailbox/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb
index c48abae66c..ec4111fefa 100644
--- a/actionmailbox/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb
+++ b/actionmailbox/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb
@@ -1,52 +1,54 @@
 # frozen_string_literal: true
 
-# Ingests inbound emails from SendGrid. Requires an +email+ 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 SendGrid ingress can learn its password. You should only use the SendGrid 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 SendGrid
-# - <tt>422 Unprocessable Entity</tt> if the request is missing the required +email+ 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 SendGrid:
-#
-#        # config/environments/production.rb
-#        config.action_mailbox.ingress = :sendgrid
-#
-# 2. Generate a strong password that Action Mailbox can use to authenticate requests to the SendGrid 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 SendGrid Inbound Parse}{https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/}
-#    to forward inbound emails to +/rails/action_mailbox/sendgrid/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 SendGrid with the following fully-qualified URL:
-#
-#        https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails
-#
-#    *NOTE:* When configuring your SendGrid Inbound Parse webhook, be sure to check the box labeled *"Post the raw,
-#    full MIME message."* Action Mailbox needs the raw MIME message to work.
-class ActionMailbox::Ingresses::Sendgrid::InboundEmailsController < ActionMailbox::BaseController
-  before_action :authenticate_by_password
+module ActionMailbox
+  # Ingests inbound emails from SendGrid. Requires an +email+ 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 SendGrid ingress can learn its password. You should only use the SendGrid 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 SendGrid
+  # - <tt>422 Unprocessable Entity</tt> if the request is missing the required +email+ 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 SendGrid:
+  #
+  #        # config/environments/production.rb
+  #        config.action_mailbox.ingress = :sendgrid
+  #
+  # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the SendGrid 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 SendGrid Inbound Parse}{https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/}
+  #    to forward inbound emails to +/rails/action_mailbox/sendgrid/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 SendGrid with the following fully-qualified URL:
+  #
+  #        https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails
+  #
+  #    *NOTE:* When configuring your SendGrid Inbound Parse webhook, be sure to check the box labeled *"Post the raw,
+  #    full MIME message."* Action Mailbox needs the raw MIME message to work.
+  class Ingresses::Sendgrid::InboundEmailsController < ActionMailbox::BaseController
+    before_action :authenticate_by_password
 
-  def create
-    ActionMailbox::InboundEmail.create_and_extract_message_id! params.require(:email)
+    def create
+      ActionMailbox::InboundEmail.create_and_extract_message_id! params.require(:email)
+    end
   end
 end