multi_mail 0.0.1 → 0.0.2

data/lib/multi_mail/mandrill/receiver.rb

@@ -1,71 +1,113 @@
 module MultiMail
   module Receiver
+    # Mandrill's incoming email receiver.
+    #
+    # Mandrill uses an HTTP header to ensure a request originates from Mandrill.
+    #
+    # @see http://help.mandrill.com/entries/23704122-Authenticating-webhook-requests
     class Mandrill < MultiMail::Service
       include MultiMail::Receiver::Base
 
-      requires :mandrill_api_key
+      recognizes :spamassassin_threshold
 
+      # Initializes a Mandrill incoming email receiver.
+      #
       # @param [Hash] options required and optional arguments
-      # @option opts [String] :mandrill_api_key a Mandrill API key
+      # @option option [Float] :spamassassin_threshold the SpamAssassin score
+      #   needed to flag a message as spam
       def initialize(options = {})
         super
-        @mandrill_api_key = options[:mandrill_api_key]
+        @spamassassin_threshold = options[:spamassassin_threshold] || 5
       end
 
+      # Transforms the content of Mandrill's webhook into a list of messages.
+      #
       # @param [Hash] params the content of Mandrill's webhook
-      # @return [Boolean] whether the request originates from Mandrill
-      def valid?(params)
-        JSON.parse(params['mandrill_events']).all? do |event|
+      # @return [Array<Mail::Message>] messages
+      # @see http://help.mandrill.com/entries/22092308-What-is-the-format-of-inbound-email-webhooks-
+      def transform(params)
+        # JSON is necessarily UTF-8.
+        JSON.parse(params['mandrill_events']).select do |event|
           event.fetch('event') == 'inbound'
-        end
-      end
+        end.map do |event|
+          msg = event['msg']
 
-      # @param [Mail::Message] message a message
-      # @return [Boolean] whether the message is spam
-      def spam?(message)
-        false
-      end
+          headers = Multimap.new
+          msg['headers'].each do |key,value|
+            if Array === value
+              value.each do |v|
+                headers[key] = v
+              end
+            else
+              headers[key] = value
+            end
+          end
 
-      # @param [Hash] params the content of Mandrill's webhook
-      # @return [Array<Mail::Message>] messages
-      # @todo parse attachments properly
-      def transform(params)
-        JSON.parse(params['mandrill_events']).map do |event|
+          this = self
           message = Mail.new do
-            headers event['msg']['headers'].reject{|k,_| k=='Received'} # @todo
+            headers headers
 
             # The following are redundant with `message-headers`:
             #
-            # address = Mail::Address.new event['msg']['from_email']
-            # address.display_name = event['msg']['from_name']
+            # address = Mail::Address.new(msg['from_email'])
+            # address.display_name = msg['from_name']
             #
             # from    address.format
-            # to      event['msg']['to'].flatten.compact
-            # subject event['msg']['subject']
+            # to      msg['to'].flatten.compact
+            # subject msg['subject']
 
             text_part do
-              body event['msg']['text']
+              body msg['text']
             end
 
-            html_part do
-              content_type 'text/html; charset=UTF-8' # unsure about charset
-              body event['msg']['html']
+            # If an email contains multiple HTML parts, Mandrill will only
+            # include the first HTML part in its `html` parameter. We therefore
+            # parse its `raw_msg` parameter to set the HTML part correctly.
+            html = this.class.condense(Mail.new(msg['raw_msg'])).parts.find do |part|
+              part.content_type == 'text/html; charset=UTF-8'
             end
-          end
 
-          # Extra Mandrill parameters. Discard `raw_msg`.
-          [ 'email',
-            'tags',
-            'sender',
-          ].each do |key|
-            if !event['msg'][key].nil? && !event['msg'][key].empty?
-              message[key] = event['msg'][key]
+            if html
+              html_part do
+                content_type 'text/html; charset=UTF-8'
+                body html.body.decoded
+              end
+            elsif msg.key?('html')
+              html_part do
+                content_type 'text/html; charset=UTF-8'
+                body msg['html']
+              end
+            end
+
+            if msg.key?('attachments')
+              msg['attachments'].each do |_,attachment|
+                add_file(:filename => attachment['name'], :content => attachment['content'])
+              end
             end
           end
 
+          # Extra Mandrill parameters. Discard `sender` and `tags`, which are
+          # null according to the docs, `matched_rules` within `spam_report`,
+          # `detail` within `spf`, which is just a human-readable version of
+          # `result`, and `raw_msg`.
+          message['ts']                = event['ts']
+          message['email']             = msg['email']
+          message['dkim-signed']       = msg['dkim']['signed'].to_s
+          message['dkim-valid']        = msg['dkim']['valid'].to_s
+          message['spam_report-score'] = msg['spam_report']['score']
+          message['spf-result']        = msg['spf']['result']
+
           message
         end
       end
+
+      # Returns whether a message is spam.
+      #
+      # @param [Mail::Message] message a message
+      # @return [Boolean] whether the message is spam
+      def spam?(message)
+        message['spam_report-score'] && message['spam_report-score'].value.to_f > @spamassassin_threshold
+      end
     end
   end
 end

data/lib/multi_mail/mandrill/sender.rb

@@ -0,0 +1,14 @@
+module MultiMail
+  module Sender
+    class Mandrill < MultiMail::Service
+      include MultiMail::Sender::Base
+
+      #requires :
+
+      # @param [Hash] options required and optional arguments
+      def initialize(options = {})
+        super
+      end
+    end
+  end
+end

data/lib/multi_mail/postmark/receiver.rb

@@ -0,0 +1,68 @@
+module MultiMail
+  module Receiver
+    # Postmark's incoming email receiver.
+    class Postmark < MultiMail::Service
+      include MultiMail::Receiver::Base
+
+      def transform(params)
+        headers = Multimap.new
+        params['Headers'].each do |header|
+          headers[header['Name']] = header['Value']
+        end
+
+        # Due to scoping issues, we can't call `transform_address` within `Mail.new`.
+        from = transform_address(params['FromFull'])
+        to   = params['ToFull'].map{|hash| transform_address(hash)}
+        cc   = params['CcFull'].map{|hash| transform_address(hash)}
+
+        message = Mail.new do
+          headers headers
+
+          from      from
+          to        to
+          cc        cc
+          reply_to  params['ReplyTo']
+          subject   params['Subject']
+          date      params['Date']
+
+          text_part do
+            body params['TextBody']
+          end
+
+          html_part do
+            content_type 'text/html; charset=UTF-8'
+            body CGI.unescapeHTML(params['HtmlBody'])
+          end
+
+          params['Attachments'].each do |attachment|
+            add_file(:filename => attachment['Name'], :content => Base64.decode64(attachment['Content']))
+          end
+        end
+
+        # Extra Postmark parameters.
+        %w(MailboxHash MessageID Tag).each do |key|
+          if params.key?(key) && !params[key].empty?
+            message[key] = params[key]
+          end
+        end
+
+        [message]
+      end
+
+      # @param [Mail::Message] message a message
+      # @return [Boolean] whether the message is spam
+      # @see http://developer.postmarkapp.com/developer-inbound-parse.html#spam
+      def spam?(message)
+        message['X-Spam-Status'].value == 'Yes'
+      end
+
+    private
+
+      def transform_address(hash)
+        address = Mail::Address.new(hash['Email'])
+        address.display_name = hash['Name']
+        address.to_s
+      end
+    end
+  end
+end

data/lib/multi_mail/postmark/sender.rb

@@ -0,0 +1,14 @@
+module MultiMail
+  module Sender
+    class Postmark < MultiMail::Service
+      include MultiMail::Sender::Base
+
+      #requires :
+
+      # @param [Hash] options required and optional arguments
+      def initialize(options = {})
+        super
+      end
+    end
+  end
+end

data/lib/multi_mail/receiver/base.rb

@@ -1,6 +1,6 @@
 module MultiMail
   module Receiver
-    # Abstract class for incoming email services.
+    # Abstract class for incoming email receivers.
     #
     # The `transform` instance method must be implemented in sub-classes. The
     # `valid?` and `spam?` instance methods may be implemented in sub-classes.
@@ -11,30 +11,39 @@ module MultiMail
         end
       end
 
-      # @param [String,Hash] raw raw POST data or a params hash
+      # Ensures a request is authentic, parses it into a params hash, and
+      # transforms it into a list of messages.
+      #
+      # @param [String,Array,Hash,Rack::Request] raw raw POST data or a params hash
       # @return [Array<Mail::Message>] messages
-      # @raises [ForgedRequest] if the request is not authentic
+      # @raise [ForgedRequest] if the request is not authentic
       def process(raw)
-        params = self.class.parse raw
-        if valid? params
-          transform params
+        params = self.class.parse(raw)
+        if valid?(params)
+          transform(params)
         else
           raise ForgedRequest
         end
       end
 
+      # Returns whether a request is authentic.
+      #
       # @param [Hash] params the content of the provider's webhook
       # @return [Boolean] whether the request is authentic
       def valid?(params)
         true
       end
 
+      # Transforms the content of a provider's webhook into a list of messages.
+      #
       # @param [Hash] params the content of the provider's webhook
       # @return [Array<Mail::Message>] messages
       def transform(params)
         raise NotImplementedError
       end
 
+      # Returns whether a message is spam.
+      #
       # @param [Mail::Message] message a message
       # @return [Boolean] whether the message is spam
       def spam?(message)
@@ -42,23 +51,131 @@ module MultiMail
       end
 
       module ClassMethods
+        # ActionDispatch::Http::Request subclasses Rack::Request and turns
+        # attachment hashes into instances of ActionDispatch::Http::UploadedFile
+        # in Rails 3 and 4 and instances of ActionController::UploadedFile in
+        # Rails 2.3, both of which have the same interface.
+        #
+        # @param [ActionDispatch::Http::UploadedFile,ActionController::UploadedFile,Hash] attachment an attachment
+        # @return [Hash] arguments for `Mail::Message#add_file`
+        def add_file_arguments(attachment)
+          if Hash === attachment
+            {:filename => attachment[:filename], :content => attachment[:tempfile].read}
+          else
+            {:filename => attachment.original_filename, :content => attachment.read}
+          end
+        end
+
+        # Parses raw POST data into a params hash.
+        #
         # @param [String,Hash] raw raw POST data or a params hash
+        # @raise [ArgumentError] if the argument is not a string or a hash
         def parse(raw)
           case raw
           when String
-            params = CGI.parse raw
-            params.each do |key,value|
+            begin
+              JSON.parse(raw)
+            rescue JSON::ParserError
+              params = CGI.parse(raw)
+
+              # Flatten the parameters.
+              params.each do |key,value|
+                if Array === value && value.size == 1
+                  params[key] = value.first
+                end
+              end
+
+              params
+            end
+          when Array
+            params = {}
+
+            # Collect the values for each key.
+            map = Multimap.new
+            raw.each do |key,value|
+              map[key] = value
+            end
+
+            # Flatten the parameters.
+            map.each do |key,value|
               if Array === value && value.size == 1
                 params[key] = value.first
+              else
+                params[key] = value
               end
             end
+
             params
+          when Rack::Request
+            raw.params
           when Hash
             raw
           else
             raise ArgumentError, "Can't handle #{raw.class.name} input"
           end
         end
+
+        # Condenses a message's HTML parts to a single HTML part.
+        #
+        # @example
+        #   flat = self.class.condense(message.dup)
+        #
+        # @param [Mail::Message] message a message with zero or more HTML parts
+        # @return [Mail::Message] the message with a single HTML part
+        def condense(message)
+          if message.multipart? && message.parts.any?(&:multipart?)
+            # Get the message parts as a flat array.
+            result = flatten(Mail.new, message.parts.dup)
+
+            # Rebuild the message's parts.
+            message.parts.clear
+
+            # Merge non-attachments with the same content type.
+            (result.parts - result.attachments).group_by(&:content_type).each do |content_type,group|
+              body = group.map{|part| part.body.decoded}.join
+
+              # Make content types match across all APIs.
+              if content_type == 'text/plain; charset=us-ascii'
+                # `text/plain; charset=us-ascii` is the default content type.
+                content_type = 'text/plain'
+              elsif content_type == 'text/html; charset=us-ascii'
+                content_type = 'text/html; charset=UTF-8'
+                body = body.encode('UTF-8') if body.respond_to?(:encode)
+              end
+
+              message.parts << Mail::Part.new({
+                :content_type => content_type,
+                :body => body,
+              })
+            end
+
+            # Add attachments last.
+            result.attachments.each do |part|
+              message.parts << part
+            end
+          end
+
+          message
+        end
+
+        # Flattens a hierarchy of message parts.
+        #
+        # @example
+        #   flat = self.class.flatten(Mail.new, parts.dup)
+        #
+        # @param [Mail::Message] message a message
+        # @param [Mail::PartsList] parts parts to add to the message
+        # @return [Mail::Message] the message with all the parts
+        def flatten(message, parts)
+          parts.each do |part|
+            if part.multipart?
+              flatten(message, part.parts)
+            else
+              message.parts << part
+            end
+          end
+          message
+        end
       end
     end
   end

data/lib/multi_mail/receiver.rb

@@ -1,8 +1,10 @@
 module MultiMail
+  # Endpoint for initializing different incoming email receivers.
+  #
   # @see http://rdoc.info/gems/fog/Fog/Storage
   module Receiver
-    autoload :Base, 'multi_mail/receiver/base'
-
+    # Initializes an incoming email receiver.
+    #
     # @example
     #   require 'multi_mail'
     #   service = MultiMail::Receiver.new({
@@ -11,8 +13,9 @@ module MultiMail
     #   })
     #
     # @param [Hash] attributes required arguments
-    # @option opts [String,Symbol] :provider a provider
-    # @raises [ArgumentError] if the provider does not exist
+    # @option attributes [String,Symbol] :provider a provider
+    # @return [MultiMail::Service] an incoming email receiver
+    # @raise [ArgumentError] if the provider does not exist
     # @see Fog::Storage::new
     def self.new(attributes)
       attributes = attributes.dup # prevent delete from having side effects
@@ -32,6 +35,9 @@ module MultiMail
       when :sendgrid
         require 'multi_mail/sendgrid/receiver'
         MultiMail::Receiver::SendGrid.new(attributes)
+      when :simple
+        require 'multi_mail/simple/receiver'
+        MultiMail::Receiver::Simple.new(attributes)
       when :mock
         # for testing
         MultiMail::Receiver::Mock.new(attributes)

data/lib/multi_mail/sender/base.rb

@@ -0,0 +1,7 @@
+module MultiMail
+  module Sender
+    # Abstract class for outgoing email services.
+    module Base
+    end
+  end
+end

data/lib/multi_mail/sender.rb

@@ -1,8 +1,10 @@
 module MultiMail
+  # Endpoint for initializing different outgoing email senders.
+  #
   # @see http://rdoc.info/gems/fog/Fog/Storage
   module Sender
-    autoload :Base, 'multi_mail/sender/base'
-
+    # Initializers an outgoing email sender.
+    #
     # @example
     #   require 'multi_mail'
     #   service = MultiMail::Sender.new({
@@ -11,8 +13,9 @@ module MultiMail
     #   })
     #
     # @param [Hash] attributes required arguments
-    # @option opts [String,Symbol] :provider a provider
-    # @raises [ArgumentError] if the provider does not exist
+    # @option attributes [String,Symbol] :provider a provider
+    # @return [MultiMail::Service] an outgoing email sender
+    # @raise [ArgumentError] if the provider does not exist
     # @see Fog::Storage::new
     def self.new(attributes)
       attributes = attributes.dup # prevent delete from having side effects
@@ -29,6 +32,9 @@ module MultiMail
       when :sendgrid
         require 'multi_mail/sendgrid/sender'
         MultiMail::Sender::SendGrid.new(attributes)
+      when :simple
+        require 'multi_mail/simple/sender'
+        MultiMail::Sender::Simple.new(attributes)
       when :mock
         # for testing
         MultiMail::Sender::Mock.new(attributes)

data/lib/multi_mail/sendgrid/receiver.rb

@@ -0,0 +1,42 @@
+module MultiMail
+  module Receiver
+    class SendGrid < MultiMail::Service
+      include MultiMail::Receiver::Base
+
+      requires :sendgrid_username
+      requires :sendgrid_password
+      recognizes :http_post_format
+      attr_reader :http_post_format
+
+      def initialize(options = {})
+        super
+        @sendgrid_username = options[:sendgrid_username]
+        @sendgrid_password = options[:sendgrid_password]
+        @http_post_format = options[:http_post_format]
+      end
+
+      def transform(params)
+        attachments = 1.upto(params['attachments'].to_i).map do |num|
+          attachment_from_params(params["attachment#{num}"])
+        end
+
+        @message = Mail.new do
+          header params['headers']
+
+          body params['text']
+
+          html_part do
+            content_type 'text/html; charset=UTF-8'
+            body params['html']
+          end if params['html']
+
+          attachments.each do |attachment|
+            add_file(attachment)
+          end
+        end
+      end
+    end
+  end
+end
+
+

data/lib/multi_mail/sendgrid/sender.rb

@@ -0,0 +1,11 @@
+module MultiMail
+  module Sender
+    class SendGrid < MultiMail::Service
+      include MultiMail::Sender::base
+
+      def initialize(options = {})
+        super
+      end
+    end
+  end
+end

data/lib/multi_mail/service.rb

@@ -1,6 +1,10 @@
 module MultiMail
+  # Interacts with email APIs to send or receive email.
+  #
   # @see http://rdoc.info/gems/fog/Fog/Service
   class Service
+    # Initializers an email API service.
+    #
     # @param [Hash] options optional arguments
     def initialize(options = {})
       self.class.validate_options(options)
@@ -15,6 +19,8 @@ module MultiMail
         requirements.concat(args)
       end
 
+      # Returns the list of required arguments.
+      #
       # @return [Array] a list of required arguments
       # @see Fog::Service::requirements
       def requirements
@@ -29,15 +35,20 @@ module MultiMail
         recognized.concat(args)
       end
 
+      # Returns the list of optional arguments.
+      #
       # @return [Array] a list of optional arguments
       # @see Fog::Service::recognized
       def recognized
         @recognized ||= []
       end
 
+      # Ensures that required arguments are present and that optional arguments
+      # are recognized.
+      #
       # @param [Hash] options arguments
-      # @raises [ArgumentError] if can't find required arguments or can't
-      #   recognize optional arguments
+      # @raise [ArgumentError] if it can't find a required argument or can't
+      #   recognize an optional argument
       # @see Fog::Service::validate_options
       def validate_options(options)
         keys = []
@@ -48,13 +59,13 @@ module MultiMail
         end
         missing = requirements - keys
         unless missing.empty?
-          raise ArgumentError, "Missing required arguments: #{missing.join(', ')}"
+          raise ArgumentError, "Missing required arguments: #{missing.map(&:to_s).sort.join(', ')}"
         end
 
         unless recognizes.empty?
           unrecognized = options.keys - requirements - recognized
           unless unrecognized.empty?
-            raise ArgumentError, "Unrecognized arguments: #{unrecognized.join(', ')}"
+            raise ArgumentError, "Unrecognized arguments: #{unrecognized.map(&:to_s).sort.join(', ')}"
           end
         end
       end

data/lib/multi_mail/simple/receiver.rb

@@ -0,0 +1,15 @@
+module MultiMail
+  module Receiver
+    class Simple < MultiMail::Service
+      include MultiMail::Receiver::Base
+      # Expects the value of the "message" query string parameter to be a raw
+      # email message parsable by the Mail gem.
+      #
+      # @param [Hash] params the content of the webhook
+      # @return [Array<Mail::Message>] messages
+      def transform(params)
+        [Mail.new(params['message'])]
+      end
+    end
+  end
+end

data/lib/multi_mail/simple/sender.rb

@@ -0,0 +1,14 @@
+module MultiMail
+  module Sender
+    class Simple < MultiMail::Service
+      include MultiMail::Sender::Base
+
+      #requires :
+
+      # @param [Hash] options required and optional arguments
+      def initialize(options = {})
+        super
+      end
+    end
+  end
+end

data/lib/multi_mail/version.rb

@@ -1,3 +1,3 @@
 module MultiMail
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end