diff options
author | George Claghorn <george@basecamp.com> | 2018-12-13 10:05:53 -0500 |
---|---|---|
committer | George Claghorn <george@basecamp.com> | 2018-12-13 10:05:53 -0500 |
commit | cbb2bdafd91edfb515c0e440c050bc5a542f8438 (patch) | |
tree | 4cac6dd45a5fb6605bbd08d303857679bd8cf5bd /app/controllers/action_mailbox/ingresses/postfix | |
parent | 7a2ff4ea093dac8b8ad20e6f17679b972f7f967a (diff) | |
download | rails-cbb2bdafd91edfb515c0e440c050bc5a542f8438.tar.gz rails-cbb2bdafd91edfb515c0e440c050bc5a542f8438.tar.bz2 rails-cbb2bdafd91edfb515c0e440c050bc5a542f8438.zip |
Document the ingress controllers
Diffstat (limited to 'app/controllers/action_mailbox/ingresses/postfix')
-rw-r--r-- | app/controllers/action_mailbox/ingresses/postfix/inbound_emails_controller.rb | 41 |
1 files changed, 41 insertions, 0 deletions
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 |