/action_mailbox_amazon_ingress

Rails ActionMailbox ingress for Amazon SES

Primary LanguageRubyMIT LicenseMIT

ActionMailboxAmazonIngress

Provides Amazon SES/SNS integration with Rails ActionMailbox.

Installation

Add this line to your application's Gemfile:

gem 'action_mailbox_amazon_ingress', '~> 0.1.3'

Configuration

Amazon SES/SNS

  1. Configure SES to (save emails to S3)(https://docs.aws.amazon.com/ses/latest/dg/receiving-email-action-s3.html) or to send them as raw messages.

  2. Configure the SNS topic for SES or for the S3 action to send notifications to +/rails/action_mailbox/amazon/inbound_emails+. For example, if your website is hosted at https://www.example.com then configure SNS to publish the SES notification topic to this HTTP endpoint: https://example.com/rails/action_mailbox/amazon/inbound_emails

Rails

  1. Configure ActionMailbox to accept emails from Amazon SES:
# config/environments/production.rb
config.action_mailbox.ingress = :amazon
  1. Configure which SNS topics will be accepted:
# config/environments/production.rb
config.action_mailbox.amazon.subscribed_topics = %w(
  arn:aws:sns:eu-west-1:123456789001:example-topic-1
  arn:aws:sns:us-east-1:123456789002:example-topic-2
)

SNS Subscriptions will now be auto-confirmed and messages will be automatically handled via ActionMailbox.

Note that even if you manually confirm subscriptions you will still need to provide a list of subscribed topics; messages from unrecognized topics will be ignored.

See ActionMailbox documentation for full usage information.

Testing

RSpec

Two RSpec request spec helpers are provided to facilitate testing Amazon SNS/SES notifications in your application:

  • amazon_ingress_deliver_subscription_confirmation
  • amazon_ingress_deliver_email

Include the ActionMailboxAmazonIngress::RSpec extension in your tests:

# spec/rails_helper.rb

require 'action_mailbox_amazon_ingress/rspec'

RSpec.configure do |config|
  config.include ActionMailboxAmazonIngress::RSpec
end

Configure your test environment to accept the default topic used by the provided helpers:

# config/environments/test.rb

config.action_mailbox.amazon.subscribed_topics = ['topic:arn:default']

Example Usage

# spec/requests/amazon_emails_spec.rb

RSpec.describe 'amazon emails', type: :request do
  it 'delivers a subscription notification' do
    amazon_ingress_deliver_subscription_confirmation
    expect(response).to have_http_status :ok
  end

  it 'delivers an email notification' do
    amazon_ingress_deliver_email(mail: Mail.new(to: 'user@example.com'))
    expect(ActionMailbox::InboundEmail.last.mail.recipients).to eql ['user@example.com']
  end
end

You may also pass the following keyword arguments to both helpers:

  • topic: The SNS topic used for each notification (default: topic:arn:default).
  • authentic: The Aws::SNS::MessageVerifier class is stubbed by these helpers; set authentic to true or false to define how it will verify incoming notifications (default: true).

Development

Setup

bin/setup

Testing

Ensure Rubocop, RSpec, and StrongVersions compliance by running make:

make

Updating AWS Fixtures

bundle exec rake sign_aws_fixtures

Contributing

Pull requests are welcome.

License

The gem is available as open source under the terms of the MIT License.