mail-ses 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a729c8707418afffdc7f0c411a4f92b66d236db4ed0d1e41940c1ab00cecdb6c
+  data.tar.gz: 45fd00d6204d3dd2764b78f5ee250f4cbf17f01a4dd6cf8671d9d55530eb9f68
+SHA512:
+  metadata.gz: aaddce5f599c511aa774e9d8daba34e2142b88ebcee3048cbcac32c5e5c09ea653e627fc0087ea76f5086e3a6de40b881a7de46b79336b523ff7a466674faffa
+  data.tar.gz: 89973fc7a007b2058e5c33f819519b06e8962e93439880799d74454ed6b52ca86dafef7adfffccd745c8fe3b70f4fcb05a66dec5b763f2c12783e1c032cbe017

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# 0.1.0
+
+- Initial release of gem.
+- Support for sending ActionMailer mails via AWS SDK v3.

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2018 TableCheck Inc.
+
+AWS::SES originally copyright (c) 2011 Drew V. Blas <drew.blas@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,121 @@
+[![Gem Version](https://badge.fury.io/rb/mail-ses.svg)](http://badge.fury.io/rb/mail-ses)
+[![Travis Status](https://travis-ci.org/tablecheck/mail-ses.svg?branch=master)](https://travis-ci.org/tablecheck/mail-ses)
+
+# Mail::SES
+
+Mail::SES is a mail delivery method handler for Amazon SES (Simple Email Service) which can be used with Rails' [Action Mailer](https://guides.rubyonrails.org/action_mailer_basics.html).
+
+This gem is inspired by [Drew Blas' AWS::SES gem](https://github.com/drewblas/aws-ses),
+but uses the official [AWS SDK v3 for SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-using-sdk-ruby.html) under-the-hood.
+By passing parameters through to the SDK, this gem supports greater flexibility with less code (including IAM instance profiles, retry parameters, etc.)
+
+### Compatibility
+
+* TBD
+
+### Shameless Plug
+
+ActionMailer::SES is sponsored by [TableCheck](http://corp.tablecheck.com/), Japan's leading restaurant management app. If **you** are a ninja-level Javascript/Ruby coder, designer, project manager, etc. and are eager to work in Tokyo with other ninjas, Japan in a dynamic environment, please get in touch at [careers@tablecheck.com](mailto:careers@tablecheck.com).
+
+## Getting Started
+
+In your `Gemfile`:
+
+```ruby
+gem 'mail-ses'
+```
+
+Next, make a new initializer at `config/initializers/mail_ses.rb`:
+
+```ruby
+ActionMailer::Base.add_delivery_method :ses, Mail::SES,
+    region: 'us-east-1',
+    access_key_id: 'abc',
+    secret_access_key: '123'
+```
+
+Finally, in the appropriate `config/environments/*.rb`:
+
+```ruby
+config.action_mailer.delivery_method = :ses
+```
+
+## Advanced Usage
+
+### AWS SES Client Options
+
+Any options supported by the `Aws::SES::Client` class can be passed into the initializer, for example:
+
+```ruby
+ActionMailer::Base.add_delivery_method :ses, Mail::SES,
+    region: 'us-east-1',
+    session_token: 'foobar',
+    retry_limit: 5,
+    retry_max_delay: 10
+```
+
+In addition, the shortcut option `:use_iam_profile (Boolean)` which activates the IAM instance profile.
+
+```ruby
+ActionMailer::Base.add_delivery_method :ses, Mail::SES,
+    region: 'us-east-1',
+    use_iam_profile: true
+```
+
+### Default Mail Options
+
+In the initializer you can set `:mail_options (Hash)` which are default options to pass-through to each mail sent:
+
+```ruby
+ActionMailer::Base.add_delivery_method :ses, Mail::SES,
+    # ...
+    mail_options: {
+      source_arn: 'arn:aws:ses:us-east-1:123456789012:identity/example.com',
+      tags: [
+        { name: 'MessageTagName', value: 'MessageTagValue' },
+      ],
+    }
+```
+
+### AWS Error Handling
+
+To handle errors from AWS API, in the initializer you can set `:error_handler (Proc)` which takes two args:
+the error which was raised, and the raw_email options hash. This is useful for notifying your bug tracking service.
+Setting `:error_handler` causes the error to be swallowed unless it is raised again in the handler itself.
+
+```ruby
+ActionMailer::Base.add_delivery_method :ses, Mail::SES,
+    # ...
+    error_handler: ->(error, raw_email) do
+      Bugsnag.notify(error){|r| r.add_tab('email', { email: raw_email })}
+      raise error    
+    end
+```
+
+### Send Email as a Standalone
+
+You can send one-off mails using the `Mail::SES` object and `#deliver` method.
+
+```ruby
+mail = Mail.new(args)
+
+ses  = Mail::SES.new(region: 'us-east-1',
+                     access_key_id: 'abc',
+                     secret_access_key: '123')
+
+options = { source_arn: 'arn:aws:ses:us-east-1:123456789012:identity/example.com' }
+
+ses.deliver!(mail, options) #=> returns AWS API response
+
+mail.message_id #=> "00000138111222aa-33322211-cccc-cccc-cccc-ddddaaaa0680-000000@email.amazonses.com"
+```
+
+Please also see the [AWS SDK v3 for SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-using-sdk-ruby.html) for alternate approaches.
+
+## Statistics, Verified Addresses, Bounce Rate, etc.
+
+Please use the official [AWS SDK v3 for SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-using-sdk-ruby.html).
+
+## Copyright
+
+Copyright (c) 2018 TableCheck Inc. See LICENSE for further details.

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/mail-ses.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+require 'aws-sdk-ses'
+require 'mail'
+require 'mail/ses'

data/lib/mail/ses.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+module Mail
+  # Mail delivery method handler for AWS SES
+  class SES
+    VERSION = File.read(File.join(File.dirname(__FILE__), '../../VERSION')).strip.freeze
+
+    RAW_EMAIL_ATTRS = %i[ source
+                          source_arn
+                          from_arn
+                          return_path_arn
+                          tags
+                          configuration_set_name ].freeze
+
+    attr_reader :client
+
+    # Initializes the Mail::SES object.
+    #
+    # options - The Hash options (optional, default: {}):
+    #   :mail_options    - (Hash) Default AWS options to set on each mail object.
+    #   :error_handler   - (Proc<Error, Hash>) Handler for AWS API errors.
+    #   :use_iam_profile - Shortcut to use AWS IAM instance profile.
+    #   All other options are passed-thru to Aws::SES::Client.
+    def initialize(options = {})
+      @mail_options = options.delete(:mail_options) || {}
+      @error_handler = options.delete(:error_handler)
+      self.class.validate_error_handler(@error_handler)
+      options = self.class.build_client_options(options)
+      @client = Aws::SES::Client.new(options)
+    end
+
+    # Delivers a Mail object via SES.
+    #
+    # mail    - The Mail object to deliver (required).
+    # options - The Hash options which override any defaults set in :mail_options
+    #           in the initializer (optional, default: {}). Refer to
+    #           Aws::SES::Client#send_raw_email
+    def deliver!(mail, options = {})
+      self.class.validate_mail(mail)
+      options = @mail_options.merge(options || {})
+      raw_email_options = self.class.build_raw_email_options(mail, options)
+      begin
+        response = client.send_raw_email(raw_email_options)
+        mail.message_id = "#{response.to_h[:message_id]}@email.amazonses.com"
+        response
+      rescue StandardError => e
+        @error_handler ? @error_handler.call(e, raw_email_options.dup) : raise(e)
+      end
+    end
+
+    class << self
+      def validate_error_handler(error_handler)
+        raise ArgumentError.new(':error_handler must be a Proc') if error_handler && !error_handler.is_a?(Proc)
+      end
+
+      def validate_mail(mail)
+        unless mail.is_a?(Mail::Message)
+          raise ArgumentError.new('mail must be an instance of Mail::Message class')
+        end
+
+        Mail::CheckDeliveryParams.check(mail)
+
+        if mail.has_attachments? && mail.text_part.nil? && mail.html_part.nil?
+          raise ArgumentError.new('Attachment provided without message body')
+        end
+      end
+
+      def build_client_options(options)
+        options[:credentials] = Aws::InstanceProfileCredentials.new if options.delete(:use_iam_profile)
+        options
+      end
+
+      def build_raw_email_options(message, options = {})
+        output = slice_hash(options, *RAW_EMAIL_ATTRS)
+        output[:source] ||= message.from.first
+        output[:destinations] = [message.to, message.cc, message.bcc].flatten.compact
+        output[:raw_message] = { data: Base64.encode64(message.to_s) }
+        output
+      end
+
+      protected
+
+      def slice_hash(hash, *keys)
+        keys.each_with_object({}) { |k, h| h[k] = hash[k] if hash.key?(k) }
+      end
+    end
+  end
+end

data/spec/mail_ses_spec.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+require 'spec_helper'
+
+RSpec.describe Mail::SES do
+  let(:ses_options) { { stub_responses: true } }
+
+  let(:ses) do
+    described_class.new(ses_options)
+  end
+
+  let(:mail) do
+    Mail.new do
+      from 'from@abc.com'
+      to %w[to1@def.com to2@xyz.com]
+      cc %w[cc1@xyz.com cc2@def.com]
+      bcc %w[bcc1@abc.com bcc2@def.com]
+      body 'This is the body'
+    end
+  end
+
+  describe '::VERSION' do
+    it { expect(described_class::VERSION).to match(/\A\d+\.\d+\.\d+/) }
+  end
+
+  describe '#initialize' do
+    it 'accepts valid :error_handler' do
+      expect(described_class.new(ses_options)).to be_a(Mail::SES)
+    end
+
+    it 'accepts valid :error_handler' do
+      expect(described_class.new(ses_options.merge(error_handler: ->(a, b) {}))).to be_a(Mail::SES)
+    end
+
+    it 'rejects invalid :error_handler' do
+      expect { described_class.new(ses_options.merge(error_handler: 'foobar')) }.to raise_error(ArgumentError, ':error_handler must be a Proc')
+    end
+
+    it 'handles :use_iam_profile option' do
+      allow_any_instance_of(Aws::InstanceProfileCredentials).to receive(:get_credentials).and_return('{}')
+      ses = described_class.new(ses_options.merge(use_iam_profile: true))
+      expect(ses.client.config.credentials).to be_a(Aws::InstanceProfileCredentials)
+    end
+
+    it 'passes through options to AWS' do
+      ses = described_class.new(ses_options.merge(log_level: :debug, retry_limit: 5))
+      expect(ses.client.config.log_level).to eq :debug
+      expect(ses.client.config.retry_limit).to eq 5
+    end
+  end
+
+  describe '#deliver!' do
+    it 'validates that mail is a Mail' do
+      expect { ses.deliver!(foo: :bar) }.to raise_error(ArgumentError, 'mail must be an instance of Mail::Message class')
+    end
+
+    it 'validates integrity of Mail' do
+      expect { ses.deliver!(Mail.new) }.to raise_error(ArgumentError, 'SMTP From address may not be blank: nil')
+      expect { ses.deliver!(Mail.new { from 'foo@bar.com' }) }.to raise_error(ArgumentError, 'SMTP To address may not be blank: []')
+    end
+
+    it 'validates attachment without body' do
+      mail.body = nil
+      mail.add_file __FILE__
+      expect { ses.deliver!(mail) }.to raise_error(ArgumentError, 'Attachment provided without message body')
+    end
+
+    context 'when options set' do
+      before { allow_any_instance_of(Mail::Message).to receive(:to_s).and_return('Fixed message body') }
+      let(:ses_options) { { stub_responses: true, mail_options: { source: 'foo@bar.com', source_arn: 'sa1' } } }
+
+      let(:exp) do
+        {
+          source: 'foo@bar.com',
+          source_arn: 'sa2',
+          destinations: %w[to1@def.com to2@xyz.com cc1@xyz.com cc2@def.com bcc1@abc.com bcc2@def.com],
+          raw_message: {
+            data: "Rml4ZWQgbWVzc2FnZSBib2R5\n"
+          }
+        }
+      end
+
+      it 'allows pass-thru and override of default options' do
+        expect(ses.client).to receive(:send_raw_email).with(exp)
+        ses.deliver!(mail, source_arn: 'sa2')
+      end
+    end
+
+    it 'sets mail.message_id' do
+      ses.deliver!(mail)
+      expect(mail.message_id).to eq('MessageId@email.amazonses.com')
+    end
+
+    it 'returns the AWS response' do
+      expect(ses.deliver!(mail)).to be_a(Seahorse::Client::Response)
+    end
+
+    context 'error handling' do
+      before { allow_any_instance_of(Aws::SES::Client).to receive(:send_raw_email).and_raise(RuntimeError.new('test')) }
+
+      context 'when :error_handler not set' do
+        it 'raises the error' do
+          expect { ses.deliver!(mail) }.to raise_error(RuntimeError, 'test')
+        end
+      end
+
+      context 'when :error_handler set' do
+        let(:ses_options) { { stub_responses: true, error_handler: ->(a, b) {} } }
+
+        it 'calls the error handler' do
+          expect(ses_options[:error_handler]).to receive(:call).and_call_original
+          ses.deliver!(mail)
+        end
+      end
+    end
+  end
+
+  describe '::build_raw_email_options' do
+    let(:options) { {} }
+    subject { described_class.build_raw_email_options(mail, options) }
+    before { allow_any_instance_of(Mail::Message).to receive(:to_s).and_return('Fixed message body') }
+
+    context 'without options' do
+      let(:exp) do
+        {
+          source: 'from@abc.com',
+          destinations: %w[to1@def.com to2@xyz.com cc1@xyz.com cc2@def.com bcc1@abc.com bcc2@def.com],
+          raw_message: {
+            data: "Rml4ZWQgbWVzc2FnZSBib2R5\n"
+          }
+        }
+      end
+
+      it { expect(subject).to eq(exp) }
+    end
+
+    context 'with options' do
+      let(:options) do
+        { source: 'source@source.com',
+          source_arn: 'source_arn',
+          from_arn: 'from_arn',
+          return_path_arn: 'return_path_arn',
+          tags: [{ name: 'Name', value: 'Value' }],
+          configuration_set_name: 'configuration_set_name',
+          other: 'other' }
+      end
+
+      let(:exp) do
+        {
+          source: 'source@source.com',
+          source_arn: 'source_arn',
+          from_arn: 'from_arn',
+          return_path_arn: 'return_path_arn',
+          tags: [
+            { name: 'Name', value: 'Value' }
+          ],
+          configuration_set_name: 'configuration_set_name',
+          destinations: %w[to1@def.com to2@xyz.com cc1@xyz.com cc2@def.com bcc1@abc.com bcc2@def.com],
+          raw_message: {
+            data: "Rml4ZWQgbWVzc2FnZSBib2R5\n"
+          }
+        }
+      end
+
+      it { expect(subject).to eq(exp) }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec'
+
+Bundler.setup
+
+require 'mail-ses'
+
+RSpec.configure do |config|
+  config.disable_monkey_patching!
+
+  config.default_formatter = 'doc' if config.files_to_run.one?
+
+  config.order = :random
+
+  Kernel.srand config.seed
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: mail-ses
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Johnny Shields
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-08-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ses
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.5
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.57.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.57.0
+description: Ruby Mail delivery method handler for Amazon SES
+email: info@tablecheck.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- VERSION
+- lib/mail-ses.rb
+- lib/mail/ses.rb
+- spec/mail_ses_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/tablecheck/mail-ses
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: Ruby Mail delivery method handler for Amazon SES
+test_files:
+- spec/mail_ses_spec.rb
+- spec/spec_helper.rb