aws-ses-rails31 0.4.3

data/lib/aws/ses/addresses.rb

@@ -0,0 +1,75 @@
+module AWS
+  module SES
+    # AWS::SES::Addresses provides for:
+    # * Listing verified e-mail addresses
+    # * Adding new e-mail addresses to verify
+    # * Deleting verified e-mail addresses
+    #
+    # You can access these methods as follows:
+    #
+    #   ses = AWS::SES::Base.new( ... connection info ... )
+    #
+    #   # Get a list of verified addresses
+    #   ses.addresses.list.result
+    #
+    #   # Add a new e-mail address to verify
+    #   ses.addresses.verify('jon@example.com')
+    #
+    #   # Delete an e-mail address
+    #   ses.addresses.delete('jon@example.com')
+    class Addresses < Base
+      def initialize(ses)
+        @ses = ses
+      end
+
+      # List all verified e-mail addresses
+      # 
+      # Usage:
+      # ses.addresses.list.result
+      # =>
+      # ['email1@example.com', email2@example.com']
+      def list
+        @ses.request('ListVerifiedEmailAddresses')
+      end
+      
+      def verify(email)
+        @ses.request('VerifyEmailAddress',
+          'EmailAddress' => email
+        )
+      end
+      
+      def delete(email)
+        @ses.request('DeleteVerifiedEmailAddress',
+          'EmailAddress' => email
+        )
+      end
+    end
+    
+    class ListVerifiedEmailAddressesResponse < AWS::SES::Response
+      def result
+        if members = parsed['ListVerifiedEmailAddressesResult']['VerifiedEmailAddresses']
+          [members['member']].flatten
+        else
+          []
+        end
+      end
+      memoized :result
+    end
+    
+    class VerifyEmailAddressResponse < AWS::SES::Response
+    end
+    
+    class DeleteVerifiedEmailAddressResponse < AWS::SES::Response
+      def result
+        success?
+      end
+    end
+    
+    class Base
+      def addresses
+        @addresses ||= Addresses.new(self)
+      end
+    end
+    
+  end
+end

data/lib/aws/ses/base.rb

@@ -0,0 +1,176 @@
+module AWS #:nodoc:
+  # AWS::SES is a Ruby library for Amazon's Simple Email Service's REST API (http://aws.amazon.com/ses).
+  # 
+  # == Getting started
+  # 
+  # To get started you need to require 'aws/ses':
+  # 
+  #   % irb -rubygems
+  #   irb(main):001:0> require 'aws/ses'
+  #   # => true
+  # 
+  # Before you can do anything, you must establish a connection using Base.new.  A basic connection would look something like this:
+  # 
+  #   ses = AWS::SES::Base.new(
+  #     :access_key_id     => 'abc', 
+  #     :secret_access_key => '123'
+  #   )
+  # 
+  # The minimum connection options that you must specify are your access key id and your secret access key.
+  module SES
+    
+    API_VERSION = '2010-12-01'
+    
+    DEFAULT_HOST = 'email.us-east-1.amazonaws.com'
+    
+    USER_AGENT = 'github-aws-ses-ruby-gem'
+    
+    # Encodes the given string with the secret_access_key by taking the
+    # hmac-sha1 sum, and then base64 encoding it.  Optionally, it will also
+    # url encode the result of that to protect the string if it's going to
+    # be used as a query string parameter.
+    #
+    # @param [String] secret_access_key the user's secret access key for signing.
+    # @param [String] str the string to be hashed and encoded.
+    # @param [Boolean] urlencode whether or not to url encode the result., true or false
+    # @return [String] the signed and encoded string.
+    def SES.encode(secret_access_key, str, urlencode=true)
+      digest = OpenSSL::Digest::Digest.new('sha256')
+      b64_hmac =
+        Base64.encode64(
+          OpenSSL::HMAC.digest(digest, secret_access_key, str)).gsub("\n","")
+
+      if urlencode
+        return CGI::escape(b64_hmac)
+      else
+        return b64_hmac
+      end
+    end
+    
+    # Generates the HTTP Header String that Amazon looks for
+    # 
+    # @param [String] key the AWS Access Key ID
+    # @param [String] alg the algorithm used for the signature
+    # @param [String] sig the signature itself
+    def SES.authorization_header(key, alg, sig)
+      "AWS3-HTTPS AWSAccessKeyId=#{key}, Algorithm=#{alg}, Signature=#{sig}"
+    end
+    
+    # AWS::SES::Base is the abstract super class of all classes who make requests against SES
+    class Base   
+      include SendEmail
+      include Info
+      
+      attr_reader :use_ssl, :server, :proxy_server, :port
+
+      # @option options [String] :access_key_id ("") The user's AWS Access Key ID
+      # @option options [String] :secret_access_key ("") The user's AWS Secret Access Key
+      # @option options [Boolean] :use_ssl (true) Connect using SSL?
+      # @option options [String] :server ("email.us-east-1.amazonaws.com") The server API endpoint host
+      # @option options [String] :proxy_server (nil) An HTTP proxy server FQDN
+      # @option options [String] :user_agent ("github-aws-ses-ruby-gem") The HTTP User-Agent header value
+      # @return [Object] the object.
+      def initialize( options = {} )
+
+        options = { :access_key_id => "",
+                    :secret_access_key => "",
+                    :use_ssl => true,
+                    :server => DEFAULT_HOST,
+                    :path => "/",
+                    :user_agent => USER_AGENT,
+                    :proxy_server => nil
+                    }.merge(options)
+
+        @server = options[:server]
+        @proxy_server = options[:proxy_server]
+        @use_ssl = options[:use_ssl]
+        @path = options[:path]
+        @user_agent = options[:user_agent]
+
+        raise ArgumentError, "No :access_key_id provided" if options[:access_key_id].nil? || options[:access_key_id].empty?
+        raise ArgumentError, "No :secret_access_key provided" if options[:secret_access_key].nil? || options[:secret_access_key].empty?
+        raise ArgumentError, "No :use_ssl value provided" if options[:use_ssl].nil?
+        raise ArgumentError, "Invalid :use_ssl value provided, only 'true' or 'false' allowed" unless options[:use_ssl] == true || options[:use_ssl] == false
+        raise ArgumentError, "No :server provided" if options[:server].nil? || options[:server].empty?
+
+        if options[:port]
+          # user-specified port
+          @port = options[:port]
+        elsif @use_ssl
+          # https
+          @port = 443
+        else
+          # http
+          @port = 80
+        end
+
+        @access_key_id = options[:access_key_id]
+        @secret_access_key = options[:secret_access_key]
+
+        # Use proxy server if defined
+        # Based on patch by Mathias Dalheimer.  20070217
+        proxy = @proxy_server ? URI.parse(@proxy_server) : OpenStruct.new
+        @http = Net::HTTP::Proxy( proxy.host,
+                                  proxy.port,
+                                  proxy.user,
+                                  proxy.password).new(options[:server], @port)
+
+        @http.use_ssl = @use_ssl
+
+        # Don't verify the SSL certificates.  Avoids SSL Cert warning in log on every GET.
+        @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+      end
+      
+      attr_accessor :settings
+      
+      def connection
+        @http
+      end
+      
+      # Make the connection to AWS passing in our request.  
+      # allow us to have a one line call in each method which will do all of the work
+      # in making the actual request to AWS.
+      def request(action, params = {})
+        # Use a copy so that we don't modify the caller's Hash, remove any keys that have nil or empty values
+        params = params.reject { |key, value| value.nil? or value.empty?}
+        
+        timestamp = Time.now.getutc
+
+        params.merge!( {"Action" => action,
+                        "SignatureVersion" => "2",
+                        "SignatureMethod" => 'HmacSHA256',
+                        "AWSAccessKeyId" => @access_key_id,
+                        "Version" => API_VERSION,
+                        "Timestamp" => timestamp.iso8601 } )
+
+        query = params.sort.collect do |param|
+          CGI::escape(param[0]) + "=" + CGI::escape(param[1])
+        end.join("&")
+
+        req = {}
+
+        req['X-Amzn-Authorization'] = get_aws_auth_param(timestamp.httpdate, @secret_access_key)
+        req['Date'] = timestamp.httpdate
+        req['User-Agent'] = @user_agent 
+
+        response = connection.post(@path, query, req)
+        
+        response_class = AWS::SES.const_get( "#{action}Response" )
+        result = response_class.new(action, response)
+        
+        if result.error?
+          raise ResponseError.new(result)
+        end
+        
+        result
+      end
+
+      # Set the Authorization header using AWS signed header authentication
+      def get_aws_auth_param(timestamp, secret_access_key)
+        encoded_canonical = SES.encode(secret_access_key, timestamp, false)
+        SES.authorization_header(@access_key_id, 'HmacSHA256', encoded_canonical)
+      end
+    end # class Base
+  end # Module SES
+end # Module AWS

data/lib/aws/ses/extensions.rb

@@ -0,0 +1,39 @@
+#:stopdoc:
+module Kernel
+  def __method__(depth = 0)
+    caller[depth][/`([^']+)'/, 1]
+  end if RUBY_VERSION <= '1.8.7'
+  
+  def __called_from__
+    caller[1][/`([^']+)'/, 1]
+  end if RUBY_VERSION > '1.8.7'
+  
+  def expirable_memoize(reload = false, storage = nil)
+    current_method = RUBY_VERSION > '1.8.7' ? __called_from__ : __method__(1)
+    storage = "@#{storage || current_method}"
+    if reload 
+      instance_variable_set(storage, nil)
+    else
+      if cache = instance_variable_get(storage)
+        return cache
+      end
+    end
+    instance_variable_set(storage, yield)
+  end
+end
+
+class Module
+  def memoized(method_name)
+    original_method = "unmemoized_#{method_name}_#{Time.now.to_i}"
+    alias_method original_method, method_name
+    module_eval(<<-EVAL, __FILE__, __LINE__)
+      def #{method_name}(reload = false, *args, &block)
+        expirable_memoize(reload) do
+          send(:#{original_method}, *args, &block)
+        end
+      end
+    EVAL
+  end
+end
+
+#:startdoc:

data/lib/aws/ses/info.rb

@@ -0,0 +1,100 @@
+module AWS
+  module SES
+    # Adds functionality for the statistics and info send quota data that Amazon SES makes available
+    #
+    # You can access these methods as follows:
+    #
+    #   ses = AWS::SES::Base.new( ... connection info ... )
+    #
+    # == Get the quota information
+    #   response = ses.quota
+    #   # How many e-mails you've sent in the last 24 hours
+    #   response.sent_last_24_hours
+    #   # How many e-mails you're allowed to send in 24 hours
+    #   response.max_24_hour_send
+    #   # How many e-mails you can send per second
+    #   response.max_send_rate
+    #
+    # == Get detailed send statistics 
+    # The result is a list of data points, representing the last two weeks of sending activity.
+    # Each data point in the list contains statistics for a 15-minute interval.
+    # GetSendStatisticsResponse#data_points is an array where each element is a hash with give string keys:
+    #
+    # * +Bounces+
+    # * +DeliveryAttempts+
+    # * +Rejects+
+    # * +Complaints+
+    # * +Timestamp+
+    #
+    #   response = ses.statistics
+    #   response.data_points # =>
+    #       [{"Bounces"=>"0",
+    #         "Timestamp"=>"2011-01-26T16:30:00Z",
+    #         "DeliveryAttempts"=>"1",
+    #         "Rejects"=>"0",
+    #         "Complaints"=>"0"},
+    #        {"Bounces"=>"0",
+    #         "Timestamp"=>"2011-02-09T14:45:00Z",
+    #         "DeliveryAttempts"=>"3",
+    #         "Rejects"=>"0",
+    #         "Complaints"=>"0"},
+    #        {"Bounces"=>"0",
+    #         "Timestamp"=>"2011-01-31T15:30:00Z",
+    #         "DeliveryAttempts"=>"3",
+    #         "Rejects"=>"0",
+    #         "Complaints"=>"0"},
+    #        {"Bounces"=>"0",
+    #         "Timestamp"=>"2011-01-31T16:00:00Z",
+    #         "DeliveryAttempts"=>"3",
+    #         "Rejects"=>"0",
+    #         "Complaints"=>"0"}]
+    
+    module Info
+      # Returns quota information provided by SES
+      # 
+      # The return format inside the response result will look like:
+      #   {"SentLast24Hours"=>"0.0", "MaxSendRate"=>"1.0", "Max24HourSend"=>"200.0"}
+      def quota
+        request('GetSendQuota')
+      end
+      
+      def statistics
+        request('GetSendStatistics')
+      end
+    end
+    
+    class GetSendQuotaResponse < AWS::SES::Response
+      def result
+        parsed['GetSendQuotaResult']
+      end
+      
+      def sent_last_24_hours
+        result['SentLast24Hours']
+      end
+      
+      def max_24_hour_send
+        result['Max24HourSend']
+      end
+      
+      def max_send_rate
+        result['MaxSendRate']
+      end
+    end
+    
+    class GetSendStatisticsResponse < AWS::SES::Response
+      def result
+        if members = parsed['GetSendStatisticsResult']['SendDataPoints']
+          [members['member']].flatten
+        else
+          []
+        end
+      end
+      
+      memoized :result
+      
+      def data_points
+        result
+      end
+    end
+  end
+end

data/lib/aws/ses/response.rb

@@ -0,0 +1,110 @@
+module AWS
+  module SES
+    class Response < String  
+      attr_reader :response, :body, :parsed, :action
+      
+      def initialize(action, response)
+        @action   = action
+        @response = response
+        @body     = response.body.to_s
+        super(body)
+      end
+
+      def headers
+        headers = {}
+        response.each do |header, value|
+          headers[header] = value
+        end
+        headers
+      end
+      memoized :headers
+
+      def [](header)
+        headers[header]
+      end
+
+      def each(&block)
+        headers.each(&block)
+      end
+
+      def code
+        response.code.to_i
+      end
+
+      {:success      => 200..299, :redirect     => 300..399,
+       :client_error => 400..499, :server_error => 500..599}.each do |result, code_range|
+        class_eval(<<-EVAL, __FILE__, __LINE__)
+          def #{result}? 
+            return false unless response
+            (#{code_range}).include? code
+          end
+        EVAL
+      end
+
+      def error?
+        !success? && (response['content-type'] == 'application/xml' || response['content-type'] == 'text/xml')
+      end
+
+      def error
+        parsed['Error']
+      end
+      memoized :error
+
+      def parsed
+        parse_options = { 'forcearray' => ['item', 'member'], 'suppressempty' => nil, 'keeproot' => false }
+#        parse_options = { 'suppressempty' => nil, 'keeproot' => false }
+
+        XmlSimple.xml_in(body, parse_options)
+      end
+      memoized :parsed
+      
+      # It's expected that each subclass of Response will override this method with what part of response is relevant
+      def result
+        parsed
+      end
+      
+      def request_id
+        error? ? parsed['RequestId'] : parsed['ResponseMetadata']['RequestId']
+      end
+
+      def inspect
+        "#<%s:0x%s %s %s %s>" % [self.class, object_id, request_id, response.code, response.message]
+      end
+    end  # class Response
+    
+    # Requests whose response code is between 300 and 599 and contain an <Error></Error> in their body
+    # are wrapped in an Error::Response. This Error::Response contains an Error object which raises an exception
+    # that corresponds to the error in the response body. The exception object contains the ErrorResponse, so
+    # in all cases where a request happens, you can rescue ResponseError and have access to the ErrorResponse and
+    # its Error object which contains information about the ResponseError.
+    #
+    #   begin
+    #     Bucket.create(..)
+    #   rescue ResponseError => exception
+    #    exception.response
+    #    # => <Error::Response>
+    #    exception.response.error
+    #    # => <Error>
+    #   end
+    class ResponseError < StandardError
+      attr_reader :response
+      def initialize(response)
+        @response = response
+        super("AWS::SES Response Error: #{message}")
+      end
+      
+      def code
+        @response.code
+      end
+      
+      def message
+        @response.error['Code'] + @response.error['Message']
+      end
+    
+      def inspect
+        "#<%s:0x%s %s %s '%s'>" % [self.class.name, object_id, @response.request_id, code, message]
+      end
+    end
+  end # module SES
+end  # module AWS
+

data/lib/aws/ses/send_email.rb

@@ -0,0 +1,144 @@
+module AWS
+  module SES
+    # Adds functionality for send_email and send_raw_email
+    # Use the following to send an e-mail:
+    #
+    #   ses = AWS::SES::Base.new( ... connection info ... )
+    #   ses.send_email :to        => ['jon@example.com', 'dave@example.com'],
+    #                :source    => '"Steve Smith" <steve@example.com>',
+    #                :subject   => 'Subject Line'
+    #                :text_body => 'Internal text body'
+    #
+    # By default, the email "from" display address is whatever is before the @. 
+    # To change the display from, use the format: 
+    #
+    #   "Steve Smith" <steve@example.com>
+    #
+    # You can also send Mail objects using send_raw_email:
+    # 
+    #   m = Mail.new( :to => ..., :from => ... )
+    #   ses.send_raw_email(m)
+    #
+    # send_raw_email will also take a hash and pass it through Mail.new automatically as well.
+    #
+    module SendEmail
+      
+      # Sends an email through SES
+      # 
+      # the destination parameters can be:
+      # 
+      # [A single e-mail string]  "jon@example.com"
+      # [A array of e-mail addresses]  ['jon@example.com', 'dave@example.com']
+      #
+      # ---
+      # = "Email address is not verified.MessageRejected (AWS::Error)"
+      # If you are receiving this message and you HAVE verified the [source] please <b>check to be sure you are not in sandbox mode!</b>
+      # If you have not been granted production access, you will have to <b>verify all recipients</b> as well.
+      # http://docs.amazonwebservices.com/ses/2010-12-01/DeveloperGuide/index.html?InitialSetup.Customer.html
+      # ---
+      #
+      # @option options [String] :source Source e-mail (from)
+      # @option options [String] :from alias for :source
+      # @option options [String] :to Destination e-mails
+      # @option options [String] :cc Destination e-mails
+      # @option options [String] :bcc Destination e-mails
+      # @option options [String] :subject
+      # @option options [String] :html_body
+      # @option options [String] :text_body
+      # @option options [String] :return_path The email address to which bounce notifications are to be forwarded. If the message cannot be delivered to the recipient, then an error message will be returned from the recipient's ISP; this message will then be forwarded to the email address specified by the ReturnPath parameter.
+      # @option options [String] :reply_to The reploy-to email address(es) for the message.  If the recipient replies to the message, each reply-to address will receive the reply.
+      # @option options
+      # @return [Response] the response to sending this e-mail
+      def send_email(options = {})
+        package     = {}
+        
+        package['Source'] = options[:source] || options[:from]
+        
+        add_array_to_hash!(package, 'Destination.ToAddresses', options[:to]) if options[:to]
+        add_array_to_hash!(package, 'Destination.CcAddresses', options[:cc]) if options[:cc]
+        add_array_to_hash!(package, 'Destination.BccAddresses', options[:bcc]) if options[:bcc]
+        
+        package['Message.Subject.Data'] = options[:subject]
+        
+        package['Message.Body.Html.Data'] = options[:html_body] if options[:html_body]
+        package['Message.Body.Text.Data'] = options[:text_body] || options[:body] if options[:text_body] || options[:body]
+        
+        package['ReturnPath'] = options[:return_path] if options[:return_path]
+        
+        add_array_to_hash!(package, 'ReplyToAddresses', options[:reply_to]) if options[:reply_to]
+        
+        request('SendEmail', package)
+      end
+      
+      # Sends using the SendRawEmail method
+      # This gives the most control and flexibility
+      #
+      # This uses the underlying Mail object from the mail gem
+      # You can pass in a Mail object, a Hash of params that will be parsed by Mail.new, or just a string
+      # 
+      # Note that the params are different from send_email
+      # Specifically, the following fields from send_email will NOT work:
+      #
+      # * :source
+      # * :html_body
+      # * :text_body
+      #
+      # send_email accepts the aliases of :from & :body in order to be more compatible with the Mail gem
+      #
+      # This method is aliased as deliver and deliver! for compatibility (especially with Rails)
+      #
+      # @option mail [String] A raw string that is a properly formatted e-mail message
+      # @option mail [Hash] A hash that will be parsed by Mail.new
+      # @option mail [Mail] A mail object, ready to be encoded
+      # @option args [String] :source The sender's email address
+      # @option args [String] :destinations A list of destinations for the message.
+      # @option args [String] :from alias for :source
+      # @option args [String] :to alias for :destinations
+      # @return [Response]
+      def send_raw_email(mail, args = {})
+        message = mail.is_a?(Hash) ? Mail.new(mail).to_s : mail.to_s
+        package = { 'RawMessage.Data' => Base64::encode64(message) }
+        package['Source'] = args[:from] if args[:from]
+        package['Source'] = args[:source] if args[:source]
+        if args[:destinations]
+            add_array_to_hash!(package, 'Destinations', args[:destinations])
+        else
+            add_array_to_hash!(package, 'Destinations', args[:to]) if args[:to]
+        end
+        request('SendRawEmail', package)
+      end
+
+      alias :deliver! :send_raw_email
+      alias :deliver  :send_raw_email
+      
+      private
+      
+      # Adds all elements of the ary with the appropriate member elements
+      def add_array_to_hash!(hash, key, ary)
+        cnt = 1
+        [*ary].each do |o|
+          hash["#{key}.member.#{cnt}"] = o
+          cnt += 1
+        end
+      end
+    end
+    
+    class EmailResponse < AWS::SES::Response
+      def result
+        super["#{action}Result"]
+      end
+      
+      def message_id
+        result['MessageId']
+      end
+    end
+    
+    class SendEmailResponse < EmailResponse
+    
+    end
+    
+    class SendRawEmailResponse < EmailResponse
+    
+    end
+  end
+end

data/lib/aws/ses/version.rb

@@ -0,0 +1,12 @@
+module AWS
+  module SES
+    module VERSION #:nodoc:
+      MAJOR    = '0'
+      MINOR    = '4'
+      TINY     = '2' 
+      BETA     = Time.now.to_i.to_s
+    end
+    
+    Version = [VERSION::MAJOR, VERSION::MINOR, VERSION::TINY, VERSION::BETA].compact * '.'
+  end
+end

data/lib/aws/ses.rb

@@ -0,0 +1,28 @@
+%w[ base64 cgi openssl digest/sha1 net/https net/http rexml/document time ostruct mail].each { |f| require f }
+
+begin
+  require 'URI' unless defined? URI
+rescue Exception => e
+  # nothing
+end
+
+begin
+  require 'xmlsimple' unless defined? XmlSimple
+rescue Exception => e
+  require 'xml-simple' unless defined? XmlSimple
+end
+
+$:.unshift(File.dirname(__FILE__))
+require 'ses/extensions'
+
+require 'ses/response'
+require 'ses/send_email'
+require 'ses/info'
+require 'ses/base'
+require 'ses/version'
+require 'ses/addresses'
+
+if defined?(Rails)
+  major, minor = Rails.version.split('.')
+  require 'actionmailer/ses_extension' if major == '2' && minor == '3'
+end