tt-mail-ses 1.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5199d52725461a602ecd0ef5514c670248f1cd212ccdaac40b337b5b53da7660
+  data.tar.gz: 550bcb9cdd21e6a545358119726de54d6dba80613f2be39f35e284844b5484ec
+SHA512:
+  metadata.gz: 73669644af86b647f248532e6988790a82cc2620aeebb9689f764ed5be45dab391751c038ecf7323cad734e467b0d7be0288b0b9a756f8f4cdb4a7f0ea367c93
+  data.tar.gz: b8cb0539bbc43413e76c3f1fe9e357775561d1ac51c5cce556f241d73101b6e54330a526e96da1d81d43dbdd131a7463066057fa8e66c56d5e4790a221db07d1

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+### 1.2.0.pre
+- Support options via message headers [#2](https://github.com/Teamtailor/mail-ses/pull/2)
+
+### 1.1.0
+
+- Mail Gem: Bump minimum version dependency to 2.8.1.
+
+### 1.0.5
+
+- Pass-thru invalid email addresses.
+
+### 1.0.4
+
+- Fix missing method error related to message headers.
+
+### 1.0.3
+
+- Support UTF-8 chars in from, to, etc addresses.
+
+### 1.0.2
+
+- Fix labels in being stripped from email addresses.
+- Support Reply-To address.
+
+### 1.0.1
+
+- Add compatibility with Mail gem 2.8.0.
+
+### 1.0.0
+
+- BREAKING CHANGE: Upgrade to AWS Ruby SDK v3 - SESv2 API ([@khrvi](https://github.com/khrvi))
+- Drop support for Ruby 2.5 and earlier.
+- Switch CI from Travis to Github Actions.
+- Add Rubocop to CI.
+- Refactor code.
+
+### 0.1.2
+
+- Fix: Add #settings method for conformity with other Mail delivery methods.
+
+### 0.1.1
+
+- Fix: Remove Base64 encoding from message body.
+
+### 0.1.0
+
+- Initial release of gem.
+- Support for sending ActionMailer mails via AWS SDK v3.

data/LICENSE

@@ -0,0 +1,24 @@
+Additional modifications copyright (c) 2024 Teamtailor AB
+
+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,143 @@
+[![Gem Version](https://badge.fury.io/rb/mail-ses.svg)](http://badge.fury.io/rb/mail-ses)
+[![Github Actions](https://github.com/tablecheck/mail-ses/actions/workflows/test.yml/badge.svg)](https://github.com/tablecheck/mail-ses/actions/workflows/test.yml)
+
+# 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 for Ruby v3 - SESv2](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SESV2.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
+
+* Ruby 2.6+
+* Ruby on Rails 3.2+
+* Mail gem 2.8.1+
+* AWS SDK for Ruby v3 - SESv2
+
+Please use version 0.1.x of this gem for legacy Ruby and AWS SDK support.
+
+## 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::SESV2::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: {
+      from_email_address_identity_arn: 'arn:aws:ses:us-east-1:123456789012:identity/example.com',
+      email_tags: [
+        { name: 'MessageTagName', value: 'MessageTagValue' },
+      ],
+    }
+```
+
+### Override Mail Options
+
+You can override the default mail options on a per-mail basis by passing them in the `mail` method:
+
+
+```ruby
+class ApplicationMailer < ActionMailer::Base
+  def example
+    mail(
+      to: "foo@example.com",
+      from: "bar@example.com",
+      mail_options: {
+        email_tags: [
+          { name: 'MessageTagName', value: 'MessageTagValue' },
+        ],
+      }
+    )
+  end
+end
+```
+
+### 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 = { from_email_address_identity_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) 2024 [Teamtailor](http://www.teamtailor.com/). See LICENSE for further details.

data/lib/mail/ses/message_validator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mail
+  class SES
+    # Validates a Mail::Message object before sending
+    class MessageValidator
+      # message - The Mail::Message object to be validated.
+      def initialize(message)
+        @message = message
+      end
+
+      # Validate the message.
+      def validate
+        validate_class
+        validate_delivery_params
+        validate_attachments
+      end
+
+      private
+
+      def validate_class
+        return if @message.is_a?(Mail::Message)
+
+        raise ArgumentError.new("mail must be an instance of Mail::Message class")
+      end
+
+      def validate_delivery_params
+        Mail::SmtpEnvelope.new(@message)
+      end
+
+      def validate_attachments
+        return unless @message.has_attachments? && @message.text_part.nil? && @message.html_part.nil?
+
+        raise ArgumentError.new("Attachment provided without message body")
+      end
+    end
+  end
+end

data/lib/mail/ses/options_builder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Mail
+  class SES
+    # Builds options for Aws::SESV2::Client#send_email
+    class OptionsBuilder
+      SES_FIELDS = %i[ from_email_address
+        from_email_address_identity_arn
+        reply_to_addresses
+        feedback_forwarding_email_address
+        feedback_forwarding_email_address_identity_arn
+        email_tags
+        configuration_set_name ].freeze
+
+      # message - The Mail::Message object to be sent.
+      # options - The Hash options which override any defaults
+      #           from the message.
+      def initialize(message, options = {})
+        @message = message
+        @options = options
+      end
+
+      # Returns the options for Aws::SESV2::Client#send_email.
+      def build
+        message_options.merge(ses_options, ses_options_from_message)
+      end
+
+      private
+
+      def ses_options
+        # TODO: address fields should be encoded to UTF-8
+        slice_hash(@options, *SES_FIELDS)
+      end
+
+      def ses_options_from_message
+        mail_options = @message[:mail_options]&.unparsed_value
+
+        if mail_options
+          @message[:mail_options] = nil
+          slice_hash(mail_options, *SES_FIELDS)
+        else
+          {}
+        end
+      end
+
+      def message_options
+        {
+          from_email_address: extract_value(:from)&.first,
+          reply_to_addresses: extract_value(:reply_to),
+          destination: {
+            to_addresses: extract_value(:to) || [],
+            cc_addresses: extract_value(:cc) || [],
+            bcc_addresses: extract_value(:bcc) || []
+          },
+          content: {raw: {data: @message.to_s}}
+        }.compact
+      end
+
+      def slice_hash(hash, *keys)
+        keys.each_with_object({}) { |k, h| h[k] = hash[k] if hash.key?(k) }
+      end
+
+      def extract_value(key)
+        value = @message.header[key]
+        return unless value
+
+        if value.respond_to?(:formatted)
+          value.formatted
+        elsif value.respond_to?(:unparsed_value)
+          Array(value.unparsed_value)
+        else
+          []
+        end&.map { |v| encode(v) }
+      end
+
+      def encode(value)
+        Mail::Encodings.address_encode(value)
+      end
+    end
+  end
+end

data/lib/mail/ses/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Mail
+  class SES
+    VERSION = "1.1.0.pre"
+  end
+end

data/lib/mail/ses.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "mail/ses/version"
+require "mail/ses/message_validator"
+require "mail/ses/options_builder"
+
+module Mail
+  # Mail delivery method handler for AWS SES
+  class SES
+    attr_accessor :settings
+    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::SESV2::Client.
+    def initialize(options = {})
+      @mail_options = options.delete(:mail_options) || {}
+
+      @error_handler = options.delete(:error_handler)
+      raise ArgumentError.new(":error_handler must be a Proc") if @error_handler && !@error_handler.is_a?(Proc)
+
+      @settings = {
+        return_response: options.delete(:return_response),
+        message_id_domain: options.delete(:message_id_domain)
+      }
+
+      options[:credentials] = Aws::InstanceProfileCredentials.new if options.delete(:use_iam_profile)
+      @client = Aws::SESV2::Client.new(options)
+    end
+
+    # Delivers a Mail::Message object via SES.
+    #
+    # message - The Mail::Message object to deliver (required).
+    # options - The Hash options which override any defaults set in :mail_options
+    #           in the initializer (optional, default: {}). Refer to
+    #           Aws::SESV2::Client#send_email
+    def deliver!(message, options = {})
+      MessageValidator.new(message).validate
+
+      options = @mail_options.merge(options || {})
+      send_options = OptionsBuilder.new(message, options).build
+
+      begin
+        response = client.send_email(send_options)
+        message.message_id = "#{response.to_h[:message_id]}@#{settings[:message_id_domain] || "email.amazonses.com"}"
+        settings[:return_response] ? response : self
+      rescue => e
+        handle_error(e, send_options)
+      end
+    end
+
+    private
+
+    def handle_error(error, send_options)
+      raise(error) unless @error_handler
+
+      @error_handler.call(error, send_options.dup)
+    end
+  end
+end

data/lib/mail-ses.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "aws-sdk-sesv2"
+require "mail"
+require "mail/ses"

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: tt-mail-ses
+version: !ruby/object:Gem::Version
+  version: 1.1.0.pre
+platform: ruby
+authors:
+- Jonas Brusman
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-sesv2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.27'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.27'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+- !ruby/object:Gem::Dependency
+  name: net-smtp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !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: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.41.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.41.1
+description: Ruby Mail delivery method handler for Amazon SES
+email: platform@teamtailor.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mail-ses.rb
+- lib/mail/ses.rb
+- lib/mail/ses/message_validator.rb
+- lib/mail/ses/options_builder.rb
+- lib/mail/ses/version.rb
+homepage: https://github.com/teamtailor/mail-ses
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Ruby Mail delivery method handler for Amazon SES
+test_files: []