Document the ingress controllers

5 files changed, 167 insertions, 0 deletions

diff --git a/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb b/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb
index d3998be2d4..0c04170eae 100644
--- a/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb
+++ b/app/controllers/action_mailbox/ingresses/amazon/inbound_emails_controller.rb
@@ -1,3 +1,32 @@
+# Ingests inbound emails from Amazon's Simple Email Service (SES).
+#
+# Requires the full RFC 822 message in the +content+ parameter. Authenticates requests by validating their signatures.
+#
+# 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 SES
+# - <tt>422 Unprocessable Entity</tt> if the request is missing the required +content+ parameter
+# - <tt>500 Server Error</tt> if one of the Active Record database, the Active Storage service, or
+#   the Active Job backend is misconfigured or unavailable
+#
+# == Usage
+#
+# 1. Install the {aws-sdk-sns}[https://rubygems.org/gems/aws-sdk-sns] gem:
+#
+#        # Gemfile
+#        gem "aws-sdk-sns", ">= 1.9.0", require: false
+#
+# 2. Tell Action Mailbox to accept emails from SES:
+#
+#        # config/environments/production.rb
+#        config.action_mailbox.ingress = :amazon
+#
+# 3. {Configure SES}[https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-notifications.html]
+#    to deliver emails to your application via POST requests to +/rails/action_mailbox/amazon/inbound_emails+.
+#    If your application lived at <tt>https://example.com</tt>, you would specify the fully-qualified URL
+#    <tt>https://example.com/rails/action_mailbox/amazon/inbound_emails</tt>.
 class ActionMailbox::Ingresses::Amazon::InboundEmailsController < ActionMailbox::BaseController
   before_action :authenticate
 
diff --git a/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb b/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb
index e878192603..7583e25f26 100644
--- a/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb
+++ b/app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb
@@ -1,3 +1,44 @@
+# Ingests inbound emails from Mailgun. Requires the following parameters:
+#
+# - +body-mime+: The full RFC 822 message
+# - +timestamp+: The current time according to Mailgun as the number of seconds passed since the UNIX epoch
+# - +token+: A randomly-generated, 50-character string
+# - +signature+: A hexadecimal HMAC-SHA256 of the timestamp concatenated with the token, generated using the Mailgun API key
+#
+# Authenticates requests by validating their signatures.
+#
+# 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, or if its timestamp is more than 2 minutes old
+# - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from Mailgun
+# - <tt>422 Unprocessable Entity</tt> if the request is missing required parameters
+# - <tt>500 Server Error</tt> if the Mailgun API key is missing, or one of the Active Record database,
+#   the Active Storage service, or the Active Job backend is misconfigured or unavailable
+#
+# == Usage
+#
+# 1. Give Action Mailbox your {Mailgun API key}[https://help.mailgun.com/hc/en-us/articles/203380100-Where-can-I-find-my-API-key-and-SMTP-credentials-]
+#    so it can authenticate requests to the Mailgun ingress.
+#
+#    Use <tt>rails credentials:edit</tt> to add your API key to your application's encrypted credentials under
+#    +action_mailbox.mailgun_api_key+, where Action Mailbox will automatically find it:
+#
+#        action_mailbox:
+#          mailgun_api_key: ...
+#
+#    Alternatively, provide your API key in the +MAILGUN_INGRESS_API_KEY+ environment variable.
+#
+# 2. Tell Action Mailbox to accept emails from Mailgun:
+#
+#        # config/environments/production.rb
+#        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`.
+#
+#    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>.
 class ActionMailbox::Ingresses::Mailgun::InboundEmailsController < ActionMailbox::BaseController
   before_action :authenticate
 
diff --git a/app/controllers/action_mailbox/ingresses/mandrill/inbound_emails_controller.rb b/app/controllers/action_mailbox/ingresses/mandrill/inbound_emails_controller.rb
index b32b254076..8be27009d2 100644
--- a/app/controllers/action_mailbox/ingresses/mandrill/inbound_emails_controller.rb
+++ b/app/controllers/action_mailbox/ingresses/mandrill/inbound_emails_controller.rb
@@ -1,3 +1,16 @@
+# Ingests inbound emails from Mandrill.
+#
+# Requires a +mandrill_events+ parameter containing a JSON array of Mandrill inbound email event objects.
+# Each event is expected to have a +msg+ object containing a full RFC 822 message in its +raw_msg+ property.
+#
+# 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 Mandrill
+# - <tt>422 Unprocessable Entity</tt> if the request is missing required parameters
+# - <tt>500 Server Error</tt> if the Mandrill API key is missing, or one of the Active Record database,
+#   the Active Storage service, or the Active Job backend is misconfigured or unavailable
 class ActionMailbox::Ingresses::Mandrill::InboundEmailsController < ActionMailbox::BaseController
   before_action :authenticate
 
diff --git a/app/controllers/action_mailbox/ingresses/postfix/inbound_emails_controller.rb b/app/controllers/action_mailbox/ingresses/postfix/inbound_emails_controller.rb
index 133accf651..ba04effd1f 100644
--- a/app/controllers/action_mailbox/ingresses/postfix/inbound_emails_controller.rb
+++ b/app/controllers/action_mailbox/ingresses/postfix/inbound_emails_controller.rb
@@ -1,3 +1,44 @@
+# Ingests inbound emails relayed from Postfix.
+#
+# 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.
+#
+# 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>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:
+#
+#        # config/environments/production.rb
+#        config.action_mailbox.ingress = :postfix
+#
+# 2. Generate a strong password that Action Mailbox can use to authenticate requests to the Postfix 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 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.
+#
+#    If your application lived at <tt>https://example.com</tt>, the full command would look like this:
+#
+#        URL=https://example.com/rails/action_mailbox/postfix/inbound_emails INGRESS_PASSWORD=... bin/rails action_mailbox:ingress:postfix
 class ActionMailbox::Ingresses::Postfix::InboundEmailsController < ActionMailbox::BaseController
   before_action :authenticate_by_password, :require_valid_rfc822_message
 
diff --git a/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb b/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb
index b856eb5b94..8e1d781c2c 100644
--- a/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb
+++ b/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb
@@ -1,3 +1,46 @@
+# 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