multi_mail 0.0.1 → 0.0.2

data/.travis.yml

@@ -1,3 +1,7 @@
 language: ruby
 rvm:
+  - 1.8.7
+  - 1.9.2
   - 1.9.3
+  - 2.0.0
+  - ree

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+--hide-void-return
+--embed-mixin ClassMethods
+--markup=markdown

data/Gemfile

@@ -1,4 +1,4 @@
 source "http://rubygems.org"
 
-# Specify your gem's dependencies in scraperwiki-api.gemspec
+# Specify your gem's dependencies in the gemspec
 gemspec

data/README.md

@@ -1,22 +1,19 @@
 # MultiMail: easily switch between email APIs
 
+[![Build Status](https://secure.travis-ci.org/opennorth/multi_mail.png)](http://travis-ci.org/opennorth/multi_mail)
 [![Dependency Status](https://gemnasium.com/opennorth/multi_mail.png)](https://gemnasium.com/opennorth/multi_mail)
-[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/opennorth/multi_mail)
+[![Coverage Status](https://coveralls.io/repos/opennorth/multi_mail/badge.png?branch=master)](https://coveralls.io/r/opennorth/multi_mail)
+[![Code Climate](https://codeclimate.com/github/opennorth/multi_mail.png)](https://codeclimate.com/github/opennorth/multi_mail)
 
 Many providers – including [Cloudmailin](http://www.cloudmailin.com/), [Mailgun](http://www.mailgun.com/), [Mandrill](http://mandrill.com/), [Postmark](http://postmarkapp.com/) and [SendGrid](http://sendgrid.com/) – offer APIs to send, receive, parse and forward email. MultiMail lets you easily switch between these APIs.
 
 ## Usage
 
-```ruby
-require 'multi_mail'
-
-service = MultiMail::Receiver.new({
-  :provider => 'mailgun',
-  :mailgun_api_key => 'key-xxxxxxxxxxxxxxxxxxxxxxx-x-xxxxxx',
-})
-
-message = service.process data # raw POST data or params hash
-```
+    require 'multi_mail'
+    
+    service = MultiMail::Receiver.new(:provider => 'mandrill')
+    
+    message = service.process data # raw POST data or params hash
 
 `message` is an array of [Mail::Message](https://github.com/mikel/mail) instances.
 
@@ -26,13 +23,111 @@ Incoming email:
 
 * [Mailgun](http://www.mailgun.com/)
 * [Mandrill](http://mandrill.com/)
+* [Postmark](http://postmarkapp.com/)
+* [Cloudmailin](http://www.cloudmailin.com/)
+
+Any additional information provided by an API is added to the message as a header. For example, Mailgun provides `stripped-text`, which is the message body without quoted parts or signature block. You can access it with `message['stripped-text'].value`.
+
+## Cloudmailin
+
+    service = MultiMail::Receiver.new({
+      :provider => 'cloudmailin',
+    })
+
+The default HTTP POST format is `raw`. Add a `:http_post_format` option to change the HTTP POST format, with possible values of `"multipart"`, `"json"` or `"raw"` (default). (The [original format](http://docs.cloudmailin.com/http_post_formats/original/) is deprecated.) For example:
+
+    service = MultiMail::Receiver.new({
+      :provider => 'cloudmailin',
+      :http_post_format => 'raw',
+    })
+
+**Note:** [MultiMail doesn't yet support Cloudmailin's URL attachments (attachment stores).](https://github.com/opennorth/multi_mail/issues/11) Please use regular attachments (always the case if you use the `raw` format) if you are using MultiMail.
+
+**2013-04-15:** If an email contains multiple HTML parts and you are using the `multipart` or `json` HTTP POST formats, Cloudmailin will only include the first HTML part in its `html` parameter. Use the `raw` format to avoid data loss. Cloudmailin also removes a newline from the end of each attachment.
+
+### Additional information provided by the API
+
+See [Cloudmailin's documentation](http://docs.cloudmailin.com/http_post_formats/):
+
+* `reply_plain`
+* `spf-result`
+
+## Mailgun
+
+    service = MultiMail::Receiver.new({
+      :provider => 'mailgun',
+      :mailgun_api_key => 'key-xxxxxxxxxxxxxxxxxxxxxxx-x-xxxxxx',
+    })
+
+If you have a route with a URL ending with "mime" and you are using the raw MIME format, add a `:http_post_format => 'raw'` option. For example:
+
+    service = MultiMail::Receiver.new({
+      :provider => 'mailgun',
+      :mailgun_api_key => 'key-xxxxxxxxxxxxxxxxxxxxxxx-x-xxxxxx',
+      :http_post_format => 'raw',
+    })
+
+**2013-04-15:** Mailgun's `stripped-text` and `stripped-html` parameters do not return the same parts of the message. `stripped-html` sometimes incorrectly drops non-quoted, non-signature parts of the message; `stripped-text` doesn't.
+
+### Additional information provided by the API
 
-[Attachment parsing](https://github.com/mikel/mail#attaching-and-detaching-files) on incoming email is not implemented yet. No outgoing email services are implemented yet.
+See [Mailgun's documentation](http://documentation.mailgun.net/user_manual.html#parsed-messages-parameters):
+
+* `stripped-text`
+* `stripped-signature`
+* `stripped-html`
+* `content-id-map`
+
+## Mandrill
+
+    service = MultiMail::Receiver.new({
+      :provider => 'mandrill',
+    })
+
+The default SpamAssassin score needed to flag an email as spam is `5`. Add a `:spamassassin_threshold` option to increase or decrease it. For example:
+
+    service = MultiMail::Receiver.new({
+      :provider => 'mandrill',
+      :spamassassin_threshold => 4.5,
+    })
+
+**2013-04-15:** 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. Mandrill also adds a newline to the end of each message part.
+
+### Additional information provided by the API
+
+See [Mandrill's documentation](http://help.mandrill.com/entries/22092308-What-is-the-format-of-inbound-email-webhooks-):
+
+* `ts`
+* `email`
+* `dkim-signed`
+* `dkim-valid`
+* `spam_report-score`
+* `spf-result`
+
+## Postmark
+
+    service = MultiMail::Receiver.new({
+      :provider => 'postmark',
+    })
+
+**2013-05-15:** If an email contains multiple HTML parts, Postmark will only include the first HTML part in its `HtmlBody` parameter. You cannot avoid this loss of data. Postmark is therefore not recommended.
+
+### Additional information provided by the API
+
+See [Postmark's documentation](http://developer.postmarkapp.com/developer-inbound-parse.html#mailboxhash):
+
+* `MailboxHash`
+* `MessageID`
+* `Tag`
 
 ## Bugs? Questions?
 
 This gem's main repository is on GitHub: [http://github.com/opennorth/multi_mail](http://github.com/opennorth/multi_mail), where your contributions, forks, bug reports, feature requests, and feedback are greatly welcomed.
 
+## Acknowledgements
+
+This gem is developed by [Open North](http://www.opennorth.ca/) through a partnership with the [Participatory Politics Foundation](http://www.participatorypolitics.org/).
+
 ## Copyright
 
 This gem re-uses code from [fog](https://github.com/fog/fog), released under the MIT license.

data/Rakefile

@@ -21,80 +21,103 @@ def credentials
   @credentials ||= YAML.load_file File.expand_path(File.join(File.dirname(__FILE__), 'api_keys.yml'))
 end
 
-namespace :mailgun do
+desc 'Create a Mailgun catch-all route forwarding to a postbin'
+task :mailgun do
+  require 'securerandom'
   require 'json'
   require 'rest-client'
 
-  desc 'Create a Mailgun catch-all route forwarding to a postbin'
-  task :postbin do
-
-    bin_name = ENV['BIN_NAME'] || JSON.load(RestClient.post('http://requestb.in/api/v1/bins', {}))['name']
-    bin_url  = "http://requestb.in/#{bin_name}"
+  def bin_url_and_action
+    bin_name = JSON.load(RestClient.post('http://requestb.in/api/v1/bins', {}))['name']
+    ["http://requestb.in/#{bin_name}", %(forward("#{bin_url}"))]
+  end
 
-    base_url = "https://api:#{credentials[:mailgun_api_key]}@api.mailgun.net/v2"
-    action   = %(forward("#{bin_url}"))
+  base_url = "https://api:#{credentials[:mailgun_api_key]}@api.mailgun.net/v2"
+  domain = JSON.load(RestClient.get("#{base_url}/domains"))['items'].first
 
-    domain = ENV['DOMAIN'] || "#{SecureRandom.base64(4).tr('+/=lIO0', 'pqrsxyz')}.mailgun.com"
+  if domain
+    domain_name = domain['name']
+  else
+    domain_name = "#{SecureRandom.base64(4).tr('+/=lIO0', 'pqrsxyz')}.mailgun.com"
+    puts "Creating the #{domain_name} domain..."
+    RestClient.post("#{base_url}/domains", :name => domain_name)
+  end
 
-    if JSON.load(RestClient.get("#{base_url}/domains"))['items'].empty?
-      puts "Creating the #{domain} domain..."
-      RestClient.post("#{base_url}/domains", :name => domain)
-    end
+  catch_all_route = JSON.load(RestClient.get("#{base_url}/routes"))['items'].find do |route|
+    route['expression'] == 'catch_all()'
+  end
 
-    route = JSON.load(RestClient.get("#{base_url}/routes"))['items'].find do |route|
-      route['expression'] == 'catch_all()'
+  if catch_all_route
+    action = catch_all_route['actions'].find do |action|
+      action[%r{\Aforward\("(http://requestb\.in/\w+)"\)\z}]
     end
 
-    if route
-      unless route['action'] == action
-        puts "Updating the catch_all() route..."
-        JSON.load(RestClient.put("#{base_url}/routes/#{route['id']}", :action => action))
-      end
+    if action
+      bin_url = $1
     else
-        puts "Creating a catch_all() route..."
-      JSON.load(RestClient.post("#{base_url}/routes", :expression => 'catch_all()', :action => action))
+      bin_url, action = bin_url_and_action
+      puts "Updating the catch_all() route..."
+      JSON.load(RestClient.put("#{base_url}/routes/#{catch_all_route['id']}", :action => action))
     end
-
-    puts "#{bin_url}?inspect"
+  else
+    bin_url, action = bin_url_and_action
+    puts "Creating a catch_all() route..."
+    JSON.load(RestClient.post("#{base_url}/routes", :expression => 'catch_all()', :action => action))
   end
+
+  puts "The catchall route for #{domain_name} POSTs to #{bin_url}?inspect"
 end
 
-namespace :mandrill do
+desc 'Ensure a Mandrill catch-all route forwarding to a postbin'
+task :mandrill do
   require 'mandrill'
 
-  def mandrill_api
-    @mandrill_api ||= Mandrill::API.new credentials[:mandrill_api_key]
-  end
+  api = Mandrill::API.new(credentials[:mandrill_api_key])
+  domain = api.inbound.domains.first
 
-  def mandrill_domains
-    @mandrill_domains ||= mandrill_api.inbound.domains.each_with_object({}) do |domain,domains|
-      domains[domain['domain']] = domain
-    end
-  end
+  if domain
+    domain_name = domain['domain']
+    routes = api.inbound.routes domain_name
+    match = routes.find{|route| route['pattern'] == '*'}
 
-  def mandrill_domain
-    @mandrill_domain ||= ENV['DOMAIN'] || mandrill_domains.keys.first
+    puts "The MX for #{domain_name} is not valid" unless domain['valid_mx']
+    puts "Add a catchall (*) route for #{domain_name}" if match.nil?
+    puts "The catchall route for #{domain_name} POSTs to #{match['url']}?inspect"
+  else
+    abort 'Add an inbound domain at https://mandrillapp.com/ or, if you already have your MX records set up, by sending an email through Mandrill'
   end
+end
 
-  desc 'Create a Mandrill catch-all route forwarding to a postbin'
-  task :validate do
-    if mandrill_domains.empty?
-      abort 'Add an inbound domain'
-    elsif mandrill_domains.size > 1 && ENV['DOMAIN'].nil?
-      abort "ENV['DOMAIN'] must be one of #{mandrill_domains.keys.join ', '}"
-    end
+desc 'Create a Postmark route forwarding to a postbin'
+task :postmark do
+  require 'json'
+  require 'postmark'
+  require 'rest-client'
 
-    if ENV['DOMAIN'] && !mandrill_domains.keys.include?(ENV['DOMAIN'])
-      abort "#{ENV['DOMAIN']} must be one of #{mandrill_domains.keys.join ', '}"
-    end
+  api = Postmark::ApiClient.new(credentials[:postmark_api_key])
 
-    unless mandrill_domains[mandrill_domain]['valid_mx']
-      puts "The MX for #{mandrill_domain} is not valid"
-    end
+  info = api.server_info
 
-    routes = mandrill_api.inbound.routes mandrill_domain
-    if routes.empty? || routes.none?{|route| route['pattern'] == '*'}
-      puts "Add a catchall (*) route for #{mandrill_domain}"
-    end
+  if info.key?(:inbound_hook_url)
+    url = info[:inbound_hook_url]
+  else
+    bin_name = JSON.load(RestClient.post('http://requestb.in/api/v1/bins', {}))['name']
+    url = "http://requestb.in/#{bin_name}"
+    api.update_server_info :inbound_hook_url => url
   end
+
+  puts "#{info[:inbound_hash]}@inbound.postmarkapp.com POSTs to #{url}?inspect"
+end
+
+desc 'POST a test fixture to an URL'
+task :http_post, :url, :fixture do |t,args|
+  require 'rest-client'
+
+  contents = File.read(args[:fixture])
+  io       = StringIO.new(contents)
+  socket   = Net::BufferedIO.new(io)
+  response = Net::HTTPResponse.read_new(socket)
+  body = contents[/(?:\r?\n){2,}(.+)\z/m, 1]
+
+  puts RestClient.post(args[:url], body, :content_type => response.header['content-type'])
 end

data/lib/multi_mail/cloudmailin/receiver.rb

@@ -0,0 +1,100 @@
+module MultiMail
+  module Receiver
+    # Cloudmailin's incoming email receiver.
+    #
+    # Cloudmailin recommends using basic authentication over HTTPS to ensure
+    # that a request originates from Cloudmailin.
+    #
+    # @see http://docs.cloudmailin.com/receiving_email/securing_your_email_url_target/
+    class Cloudmailin < MultiMail::Service
+      include MultiMail::Receiver::Base
+
+      recognizes :http_post_format
+
+      # Initializes a Cloudmailin incoming email receiver.
+      #
+      # @param [Hash] options required and optional arguments
+      # @option options [String] :http_post_format "multipart", "json" or "raw"
+      def initialize(options = {})
+        super
+        @http_post_format = options[:http_post_format]
+      end
+
+      # @param [Hash] params the content of Cloudmailin's webhook
+      # @return [Array<Mail::Message>] messages
+      # @see http://docs.cloudmailin.com/http_post_formats/multipart/
+      # @see http://docs.cloudmailin.com/http_post_formats/json/
+      # @see http://docs.cloudmailin.com/http_post_formats/raw/
+      def transform(params)
+        case @http_post_format
+        when 'raw', '', nil
+          message = self.class.condense(Mail.new(params['message']))
+
+          # Extra Cloudmailin parameters.
+          message['spf-result'] = params['envelope']['spf']['result']
+
+          # Discard rest of `envelope`: `from`, `to`, `recipients`,
+          # `helo_domain` and `remote_ip`.
+          [message]
+        when 'multipart', 'json'
+          headers = Multimap.new
+          params['headers'].each do |key,value|
+            if Array === value
+              value.each do |v|
+                headers[key] = v
+              end
+            else
+              headers[key] = value
+            end
+          end
+
+          # Mail changes `self`.
+          http_post_format = @http_post_format
+
+          this = self
+          message = Mail.new do
+            headers headers
+
+            text_part do
+              body params['plain']
+            end
+
+            if params.key?('html')
+              html_part do
+                content_type 'text/html; charset=UTF-8'
+                body params['html']
+              end
+            end
+
+            if params.key?('attachments')
+              if http_post_format == 'json'
+                params['attachments'].each do |attachment|
+                  add_file(:filename => attachment['file_name'], :content => Base64.decode64(attachment['content']))
+                end
+              else
+                params['attachments'].each do |_,attachment|
+                  add_file(this.class.add_file_arguments(attachment))
+                end
+              end
+            end
+          end
+
+          # Extra Cloudmailin parameters. The multipart format uses CRLF whereas
+          # the JSON format uses LF. Normalize to LF.
+          message['reply_plain'] = params['reply_plain'].gsub("\r\n", "\n")
+          message['spf-result']  = params['envelope']['spf']['result']
+
+          [message]
+        else
+          raise ArgumentError, "Can't handle Cloudmailin #{@http_post_format} HTTP POST format"
+        end
+      end
+
+      # @param [Mail::Message] message a message
+      # @return [Boolean] whether the message is spam
+      def spam?(message)
+        message['spf-result'] && message['spf-result'].value == 'fail'
+      end
+    end
+  end
+end

data/lib/multi_mail/mailgun/receiver.rb

@@ -1,20 +1,28 @@
 module MultiMail
   module Receiver
+    # Mailgun's incoming email receiver.
     class Mailgun < MultiMail::Service
       include MultiMail::Receiver::Base
 
       requires :mailgun_api_key
+      recognizes :http_post_format
 
+      # Initializes a Mailgun incoming email receiver.
+      #
       # @param [Hash] options required and optional arguments
-      # @option opts [String] :mailgun_api_key a Mailgun API key
+      # @option options [String] :mailgun_api_key a Mailgun API key
+      # @option options [String] :http_post_format "parsed" or "raw"
       def initialize(options = {})
         super
         @mailgun_api_key = options[:mailgun_api_key]
+        @http_post_format = options[:http_post_format]
       end
 
+      # Returns whether a request originates from Mailgun.
+      #
       # @param [Hash] params the content of Mailgun's webhook
       # @return [Boolean] whether the request originates from Mailgun
-      # @raises [KeyError] if the request is missing parameters
+      # @raise [IndexError] if the request is missing parameters
       # @see http://documentation.mailgun.net/user_manual.html#securing-webhooks
       def valid?(params)
         params.fetch('signature') == OpenSSL::HMAC.hexdigest(
@@ -22,53 +30,83 @@ module MultiMail
           '%s%s' % [params.fetch('timestamp'), params.fetch('token')])
       end
 
+      # Transforms the content of Mailgun's webhook into a list of messages.
+      #
       # @param [Hash] params the content of Mailgun's webhook
       # @return [Array<Mail::Message>] messages
-      # @note Mailgun sends the message headers both individually and in the
-      #   `message-headers` parameter. Only `message-headers` is documented.
-      # @todo parse attachments properly
+      # @see http://documentation.mailgun.net/user_manual.html#mime-messages-parameters
+      # @see http://documentation.mailgun.net/user_manual.html#parsed-messages-parameters
       def transform(params)
-        headers = Multimap.new
-        JSON.parse(params['message-headers']).each do |key,value|
-          headers[key] = value
-        end
+        case @http_post_format
+        when 'parsed', '', nil
+          headers = Multimap.new
+          JSON.parse(params['message-headers']).each do |key,value|
+            headers[key] = value
+          end
+
+          this = self
+          message = Mail.new do
+            headers headers
+
+            # The following are redundant with `body-mime` in raw MIME format
+            # and with `message-headers` in fully parsed format.
+            #
+            # from    params['from']
+            # sender  params['sender']
+            # to      params['recipient']
+            # subject params['subject']
+            #
+            # Mailgun POSTs all MIME headers both individually and in
+            # `message-headers`.
 
-        message = Mail.new do
-          headers headers
+            text_part do
+              body params['body-plain']
+            end
 
-          # The following are redundant with `message-headers`:
-          #
-          # from    params['from']
-          # sender  params['sender']
-          # to      params['recipient']
-          # subject params['subject']
+            if params.key?('body-html')
+              html_part do
+                content_type 'text/html; charset=UTF-8'
+                body params['body-html']
+              end
+            end
 
-          text_part do
-            body params['body-plain']
+            if params.key?('attachment-count')
+              1.upto(params['attachment-count'].to_i).each do |n|
+                attachment = params["attachment-#{n}"]
+                add_file(this.class.add_file_arguments(attachment))
+              end
+            end
           end
 
-          html_part do
-            content_type 'text/html; charset=UTF-8'
-            body params['body-html']
+          # Extra Mailgun parameters.
+          extra = [
+            'stripped-text',
+            'stripped-signature',
+            'stripped-html',
+            'content-id-map',
+          ]
+
+          # Non-plain, non-HTML body parts.
+          extra += params.keys.select do |key|
+            key[/\Abody-(?!html|plain)/]
           end
-        end
 
-        # Extra Mailgun parameters.
-        [ 'stripped-text',
-          'stripped-signature',
-          'stripped-html',
-          'attachment-count',
-          'attachment-x',
-          'content-id-map',
-        ].each do |key|
-          if !params[key].nil? && !params[key].empty?
-            message[key] = params[key]
+          extra.each do |key|
+            if params.key?(key) && !params[key].empty?
+              message[key] = params[key]
+            end
           end
-        end
 
-        [message]
+          [message]
+        when 'raw'
+          [Mail.new(params['body-mime'])]
+        else
+          raise ArgumentError, "Can't handle Mailgun #{@http_post_format} HTTP POST format"
+        end
       end
 
+      # Returns whether a message is spam.
+      #
       # @param [Mail::Message] message a message
       # @return [Boolean] whether the message is spam
       # @see http://documentation.mailgun.net/user_manual.html#spam-filter
@@ -77,7 +115,7 @@ module MultiMail
       # @note We may also inspect `X-Mailgun-SScore` and `X-Mailgun-Spf`, whose
       #   possible values are "Pass", "Neutral", "Fail" and "SoftFail".
       def spam?(message)
-        message['X-Mailgun-Sflag'].value == 'Yes'
+        message['X-Mailgun-Sflag'] && message['X-Mailgun-Sflag'].value == 'Yes'
       end
     end
   end

data/lib/multi_mail/mailgun/sender.rb

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