ses_api-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 412077631ec736027d7d9b14e46fcfca42e2d193
+  data.tar.gz: 01081ff399c203622a4514cddf6089cca15c4c58
+SHA512:
+  metadata.gz: fddfc7096b9b62780bded4527d1c57f291921a3e1ee63a5559a3e65c08bac04aa0beb00ea8acdf2ee4185001bf421c1abd15218f95194fac3086cb339d0d3409
+  data.tar.gz: a0c64ff863393372b9a736fd72682a6664ffec491806c56b0b30e9d95c807d207e6b9ae263a63c9f0d9f2836ef0ae88662ec58cc7550200c070194f36bcac043

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ses_api-rails.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Chris Ickes
+
+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,133 @@
+# SES API for Rails  
+Basic SES API integration with Rails specifically for transaction based emails - contact emails, user emails, etc.  
+
+## Install the SES API Rails gem  
+```
+# Gemfile
+gem 'ses_api-rails', git: 'https://github.com/cickes/ses_api-rails.git'
+```  
+`bundle install`  
+
+## High Level Integration Details  
+1. Create an initializer file defining your AWS credentials as constants  
+    ```
+    # config/initializers/ses_api-rails.rb
+    SesApi::Rails.configure do |config|
+      config.secret_access_key = ENV['SECRET_ACCESS_KEY']
+      config.access_key_id = Figaro.env.access_key_id
+      config.aws_region = "us-east-1"
+      config.ses_endpoint = "email.us-east-1.amazonaws.com"
+    end
+    ```
+  There are many ways to accomplish this.  The above shows 3 different methods.  Personally I recommend the [Figaro Gem](https://github.com/laserlemon/figaro).  
+
+2. Subclass the SesApi::Rails::Mailer class in your CustomMailer or in your ApplicationMailer  
+    ```
+    # app/mailers/custom_mailer.rb
+    class CustomMailer < SesApi::Rails::Mailer
+      ...
+      def contact
+        mail to: "you@example.com", subject: "Via Ses"
+      end
+    end
+    ```  
+
+3. Instantiate the mailer where appropriate.  
+    ```
+    # app/controllers/contacts_controller.rb  
+    def create
+      @contact = Contact.new(contact_params)
+      if @contact.valid?
+        CustomMailer.contact(@contact).deliver_now!
+        redirect_to contact_success_path, notice: "Thank you for your contact request."
+      else
+        render :new
+      end
+    end
+    ```
+
+## A Step By Step Example  
+1. (OPTIONAL) After the ses_api-rails gem is installed, add your Amazon AWS / SES credentials to environment variables.  
+    NOTE:  There are many ways to set environment variables.  This example uses the Figaro gem.  
+    ```
+    # Gemfile  
+    gem 'figaro'  
+    ```  
+    ```
+    `bundle install`  
+    `figaro install`  
+    ```
+    ```
+    # config/application.yml  
+    SECRET_ACCESS_KEY: "secret_access_key"  
+    AWS_ACCESS_KEY_ID: "aws_access_key_id"  
+    AWS_REGION:  "us-east-1"  
+    SES_ENDPOINT:  "email.us-east-1.amazonaws.com"
+    ```  
+
+2. Create an initializer that assigns your AWS credentials to constants.  There are multiple ways to accomplish this including simply hardcoding a string value.  The example below uses Figaro environment variables.  
+    ```
+    # config/initializers/ses_api-rails.rb
+    SesApi::Rails.configure do |config|
+      config.secret_access_key = Figaro.env.secret_access_key
+      config.access_key_id = Figaro.env.access_key_id
+      config.aws_region = Figaro.env.aws_region
+      config.ses_endpoint = Figaro.env.ses_endpoint
+    end
+    ```  
+
+3.  Create a Mailer that subclasses the SesApi::Rails::Mailer  
+    `rails g mailer ContactMailer`  
+    If you are only sending email from the Amazon Ses Api, you can subclass the ApplicationMailer.  Otherwise subclass the Mailer that will use the Ses delivery method.  
+    * Using the Amazon Ses API as the only delivery method application-wide  
+        ```
+        # app/mailers/application_mailer.rb  
+        class ApplicationMailer < SesApi::Rails::Mailer
+          default from: "from@example.com"  
+          layout 'mailer'
+        end
+        ```
+        ```
+        # app/mailers/contact_mailer.rb  
+        class ContactMailer < ApplicationMailer
+          ...
+          def contact
+            mail to: "you@example.com", subject: "Via Ses"
+          end
+        end
+        ```
+    Create a mailer view(s)  
+    ```
+    # app/views/contact_mailer/contact.html.erb  
+    <h1>Hello new contact</h1>
+    <p>Include instance variables as you like using @contact.attribute</p>
+    ```
+    ```
+    # app/views/contact_mailer/contact.text.erb  
+    This is a text version  
+    Hello new contact
+    ```  
+
+4. Instantiate the mailer where appropriate.  
+    NOTE:  This assumes that you have a form, model, etc. & is not covered in the installation guide of this gem.   
+    ```
+    # app/controllers/contacts_controller.rb  
+    ...
+    def create
+      @contact = Contact.new(contact_params)
+      if @contact.valid?
+        ContactMailer.contact(@contact).deliver_now!
+        redirect_to contact_success_path, notice: "Thank you for your contact request."
+      else
+        render :new
+      end
+    end
+    ...
+    ```
+
+## Troubleshooting
+Is the library included?  One way to do so is to autoload all library sub-directories:  
+`config.autoload_paths += Dir["#{config.root}/lib/**/"]`  
+  
+Is the time correct?  Recommended to use ntp or another time snychronization method  
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ses_api/rails"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/ses_api/rails/api.rb

@@ -0,0 +1,115 @@
+module SesApi
+  module Rails
+
+    # defines Mail::delivery_method
+    class Api < Mail::SMTP
+      # constants
+      ALGO = "AWS4-HMAC-SHA256"
+      SERVICE = "ses"
+      TERM_STR = "aws4_request"
+
+      class_attribute :conn, :mail
+
+      def initialize(values)
+        self.settings = {
+          }.merge!(values)
+
+        self.conn = Faraday.new(:url => "https://#{SesApi::Rails.configuration.ses_endpoint}") do |faraday|
+          faraday.request  :url_encoded             # form-encode POST params
+          faraday.response :logger                  # log requests to STDOUT
+          faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
+        end
+      end
+
+      def settings
+        {}
+      end
+
+      def deliver!(mail)
+        self.mail = mail
+        dt = create_datetime
+        credential_scope = create_credential_scope(dt)
+
+        response = conn.post do |req|
+          req.body = create_payload
+          hashed_payload = Digest::SHA256.hexdigest(req.body) #.downcase
+          headers = { :'X-Amz-Date' => dt, Host: "#{SesApi::Rails.configuration.ses_endpoint}", :'X-Amz-Content-Sha256' => hashed_payload }
+          headers.each do |addtl_header, value|
+            req.headers[addtl_header.to_s.camelize] = value
+          end
+          req.headers['Authorization'] = create_auth_header(dt, credential_scope, hashed_payload, headers)
+        end
+      
+        raise SesApi::Rails::SesError if response.status != 200
+      end
+
+      def create_datetime
+        # returns ISO8601 Basic format YYYYMMDD'T'HHMMSS'Z'
+        timestamp = Time.now.getutc
+        timestamp.strftime('%Y%m%dT%H%M%SZ')
+      end
+
+      def create_credential_scope(request_datetime)
+        "#{request_datetime[0,8]}/#{SesApi::Rails.configuration.aws_region}/#{SERVICE}/#{TERM_STR}"
+      end
+
+      def create_payload
+        to = mail.to.each_with_index.map { |email, i| "&Destination.ToAddresses.member.#{i+1}=#{CGI::escape(email)}"}.join
+        cc = mail.cc.each_with_index.map { |email, i| "&Destination.CCAddresses.member.#{i+1}=#{CGI::escape(email)}"}.join if mail.cc.present?
+        bcc = mail.bcc.each_with_index.map { |email, i| "&Destination.BCCAddresses.member.#{i+1}=#{CGI::escape(email)}"}.join if mail.bcc.present?
+        from = "&Source=#{CGI::escape(mail.from[0])}"
+        subject = "&Message.Subject.Data=#{CGI::escape(mail.subject)}"
+
+        if mail.body.raw_source.present?
+          body = "&Message.Body.Html.Data=#{CGI::escape(mail.body.raw_source)}&Message.Body.Html.Charset=UTF-8"
+          body << "&Message.Body.Text.Data=#{CGI::escape(mail.body.raw_source)}&Message.Body.Text.Charset=UTF-8"
+        else
+          body = "&Message.Body.Html.Data=#{CGI::escape(mail.html_part.body.raw_source)}&Message.Body.Html.Charset=UTF-8"
+          body << "&Message.Body.Text.Data=#{CGI::escape(mail.text_part.body.raw_source)}&Message.Body.Text.Charset=UTF-8"
+        end
+
+        payload = "AWSAccessKeyId=#{SesApi::Rails.configuration.access_key_id}&Action=SendEmail#{to}#{cc}#{bcc}#{body}#{subject}#{from}"
+      end
+
+      def create_canonical_request(headers, hashed_payload, signed_headers)
+        http_request_method = "POST"
+        canonical_uri = "/"
+        canonical_query_str = ""
+        canonical_headers = headers.sort.map { |k,v| "#{k.downcase}:#{v.strip}\n"}.join
+        canonical_request = [http_request_method, canonical_uri, canonical_query_str, canonical_headers, signed_headers, hashed_payload].join("\n")
+      end
+
+     def create_auth_header(request_datetime, credential_scope, hashed_payload, headers)
+        signing_key = create_signing_key(request_datetime)
+        signed_headers = headers.sort.map { |k,v| "#{k.downcase}" }.join(";")
+        string_to_sign = create_str_to_sign(request_datetime, credential_scope, headers, hashed_payload, signed_headers)
+        signing_signature = create_signature(signing_key, string_to_sign)
+        return "#{ALGO} Credential=#{SesApi::Rails.configuration.access_key_id}/#{credential_scope}, SignedHeaders=#{signed_headers}, Signature=#{signing_signature}"
+      end
+
+      def create_signing_key(request_datetime)
+        key_date = hmac("AWS4" + SesApi::Rails.configuration.secret_access_key, request_datetime[0,8])
+        key_region = hmac(key_date, SesApi::Rails.configuration.aws_region)
+        key_service = hmac(key_region, SERVICE)
+        key_credentials = hmac(key_service, TERM_STR)
+      end
+
+      def create_str_to_sign(request_datetime, credential_scope, headers, hashed_payload, signed_headers)
+        canonical_request = create_canonical_request(headers, hashed_payload, signed_headers)
+        return "#{ALGO}\n#{request_datetime}\n#{credential_scope}\n#{Digest::SHA256.hexdigest(canonical_request)}"
+      end
+
+      def create_signature(signing_key, string_to_sign)
+        hexhmac(signing_key, string_to_sign)
+      end
+
+      def hmac(key, value)
+        OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), key, value)
+      end
+
+      def hexhmac(key, value)
+        OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), key, value)
+      end
+    end
+  end
+end

data/lib/ses_api/rails/configuration.rb

@@ -0,0 +1,26 @@
+module SesApi
+  module Rails
+    class << self
+      attr_accessor :configuration
+    end
+
+    def self.configure
+      self.configuration ||= Configuration.new
+      yield configuration
+    end
+
+    class Configuration
+      attr_accessor :aws_region
+      attr_accessor :ses_endpoint
+      attr_accessor :access_key_id
+      attr_accessor :secret_access_key
+
+      def initialize
+        @aws_region = "us-east-1"
+        @ses_endpoint = "email.us-east-1.amazonaws.com"
+        @access_key_id = nil
+        @secret_access_key = nil
+      end
+    end
+  end
+end

data/lib/ses_api/rails/railtie.rb

@@ -0,0 +1,10 @@
+require 'ses_api/rails/api'
+module SesApi
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.after_initialize do
+        ActionMailer::Base.add_delivery_method :ses, SesApi::Rails::Api, {}
+      end
+    end
+  end
+end

data/lib/ses_api/rails/version.rb

@@ -0,0 +1,5 @@
+module SesApi
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/ses_api/rails.rb

@@ -0,0 +1,17 @@
+require 'mail'
+require 'faraday'
+require 'ses_api/rails/version'
+require 'ses_api/rails/configuration'
+require 'ses_api/rails/railtie'
+
+module SesApi
+  module Rails
+
+    class Mailer < ActionMailer::Base
+      self.delivery_method = :ses
+    end
+
+    class SesError < StandardError; end
+
+  end
+end

data/ses_api-rails.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ses_api/rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ses_api-rails"
+  spec.version       = SesApi::Rails::VERSION
+  spec.authors       = ["Chris Ickes"]
+  spec.email         = ["chris@ickessoftware.com"]
+
+  spec.summary       = %q{Basic Rails / Amazon SES API Integration.}
+  spec.description   = %q{Rails / Amazon SES API integration for basic transactional email sending.}
+  spec.homepage      = "https://github.com/cickes/ses_api-rails.git"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_dependency 'mail'
+  spec.add_dependency 'faraday'
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: ses_api-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Ickes
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Rails / Amazon SES API integration for basic transactional email sending.
+email:
+- chris@ickessoftware.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/ses_api/rails.rb
+- lib/ses_api/rails/api.rb
+- lib/ses_api/rails/configuration.rb
+- lib/ses_api/rails/railtie.rb
+- lib/ses_api/rails/version.rb
+- ses_api-rails.gemspec
+homepage: https://github.com/cickes/ses_api-rails.git
+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.4.5
+signing_key: 
+specification_version: 4
+summary: Basic Rails / Amazon SES API Integration.
+test_files: []