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/mailgun | |
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/mailgun')
-rw-r--r-- | app/controllers/action_mailbox/ingresses/mailgun/inbound_emails_controller.rb | 41 |
1 files changed, 41 insertions, 0 deletions
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 |