From 7a2ff4ea093dac8b8ad20e6f17679b972f7f967a Mon Sep 17 00:00:00 2001 From: George Claghorn Date: Thu, 13 Dec 2018 07:38:03 -0500 Subject: Document ingress configuration --- README.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 147 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 543cd998ee..14ddca0f26 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Action Mailbox -Action Mailbox routes incoming emails to controller-like mailboxes for further and encapsulated processing in Rails. +Action Mailbox routes incoming emails to controller-like mailboxes for further and encapsulated processing in Rails. -It ships with ingress handling for AWS SNS, Mailgun, Madrill, and Sendgrid. You can also handle inbound mails directly via the Postfix ingress task/controller combination. +It ships with ingresses for Amazon SES, Mailgun, Mandrill, and SendGrid. You can also handle inbound mails directly via the built-in Postfix ingress. The inbound emails are turned into `InboundEmail` records using Active Record and feature lifecycle tracking, storage of the original email on cloud storage via Active Storage, and responsible data handling with on-by-default incineration. @@ -24,7 +24,7 @@ Assumes a Rails 5.2+ application: # Gemfile gem "actionmailbox", github: "rails/actionmailbox", require: "action_mailbox" ``` - + 1. Install migrations needed for InboundEmail (and ensure Active Storage is setup) ``` @@ -32,9 +32,150 @@ Assumes a Rails 5.2+ application: ./bin/rails db:migrate ``` -## Configure ingress path and password +## Configuring + +### Amazon SES + +1. Install the [`aws-sdk-sns`](https://rubygems.org/gems/aws-sdk-sns) gem: + + ```ruby + # Gemfile + gem "aws-sdk-sns", ">= 1.9.0", require: false + ``` + +2. Tell Action Mailbox to accept emails from SES: + + ```ruby + # config/environments/production.rb + config.action_mailbox.ingress = :amazon + ``` + +3. [Configure SES][ses-docs] to deliver emails to your application via POST requests + to `/rails/action_mailbox/amazon/inbound_emails`. If your application lived at `https://example.com`, you would specify + the fully-qualified URL `https://example.com/rails/action_mailbox/amazon/inbound_emails`. + +[ses-docs]: https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-notifications.html + +### Mailgun + +1. Give Action Mailbox your [Mailgun API key][mailgun-api-key] so it can authenticate requests to the Mailgun ingress. + + Use `rails credentials:edit` to add your API key to your application's encrypted credentials under + `action_mailbox.mailgun_api_key`, where Action Mailbox will automatically find it: + + ```yaml + 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: + + ```ruby + # config/environments/production.rb + config.action_mailbox.ingress = :mailgun + ``` + +3. [Configure Mailgun][mailgun-forwarding] to forward inbound emails to `/rails/action_mailbox/mailgun/inbound_emails/mime`. + If your application lived at `https://example.com`, you would specify the fully-qualified URL + `https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime`. + +[mailgun-api-key]: https://help.mailgun.com/hc/en-us/articles/203380100-Where-can-I-find-my-API-key-and-SMTP-credentials- +[mailgun-forwarding]: https://documentation.mailgun.com/en/latest/user_manual.html#receiving-forwarding-and-storing-messages + +### Mandrill + +1. Give Action Mailbox your Mandrill API key so it can authenticate requests to the Mandrill ingress. + + Use `rails credentials:edit` to add your API key to your application's encrypted credentials under + `action_mailbox.mandrill_api_key`, where Action Mailbox will automatically find it: + + ```yaml + action_mailbox: + mandrill_api_key: ... + ``` + + Alternatively, provide your API key in the `MANDRILL_INGRESS_API_KEY` environment variable. + +2. Tell Action Mailbox to accept emails from Mandrill: + + ```ruby + # config/environments/production.rb + config.action_mailbox.ingress = :mandrill + ``` + +3. [Configure Mandrill][mandrill-routing] to route inbound emails to `/rails/action_mailbox/mandrill/inbound_emails`. + If your application lived at `https://example.com`, you would specify the fully-qualified URL + `https://example.com/rails/action_mailbox/mandrill/inbound_emails`. + +[mandrill-routing]: https://mandrill.zendesk.com/hc/en-us/articles/205583197-Inbound-Email-Processing-Overview + +### Postfix + +1. Tell Action Mailbox to accept emails from Postfix: + + ```ruby + # 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 `rails credentials:edit` to add the password to your application's encrypted credentials under + `action_mailbox.ingress_password`, where Action Mailbox will automatically find it: + + ```yaml + action_mailbox: + ingress_password: ... + ``` + + Alternatively, provide the password in the `RAILS_INBOUND_EMAIL_PASSWORD` environment variable. + +3. [Configure Postfix][postfix-config] to pipe inbound emails to `bin/rails action_mailbox:ingress:postfix`, providing + the `URL` of the Postfix ingress and the `INGRESS_PASSWORD` you previously generated. If your application lived at + `https://example.com`, 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 + ``` + +[postfix-config]: https://serverfault.com/questions/258469/how-to-configure-postfix-to-pipe-all-incoming-email-to-a-script + +### SendGrid + +1. Tell Action Mailbox to accept emails from SendGrid: + + ```ruby + # 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 `rails credentials:edit` to add the password to your application's encrypted credentials under + `action_mailbox.ingress_password`, where Action Mailbox will automatically find it: + + ```yaml + action_mailbox: + ingress_password: ... + ``` + + Alternatively, provide the password in the `RAILS_INBOUND_EMAIL_PASSWORD` environment variable. + +3. [Configure SendGrid Inbound Parse][sendgrid-config] 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 `https://example.com`, you would configure SendGrid with the following 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. + +[sendgrid-config]: https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/ -TODO ## Examples @@ -112,4 +253,4 @@ Action Mailbox is destined for inclusion in Rails 6, which is due to be released ## License -Action Mailbox is released under the [MIT License](https://opensource.org/licenses/MIT). \ No newline at end of file +Action Mailbox is released under the [MIT License](https://opensource.org/licenses/MIT). -- cgit v1.2.3