multi_mail 0.0.2 → 0.1.0

data/.gitignore

@@ -4,4 +4,5 @@
 Gemfile.lock
 doc/*
 pkg/*
-api_keys.yml
+spec/cassettes
+api_keys.yml

data/.travis.yml

@@ -5,3 +5,13 @@ rvm:
   - 1.9.3
   - 2.0.0
   - ree
+env:
+  global:
+    # MAILGUN_API_KEY
+    - secure: "hQrNP1++1GVNuFp7xHIUOp938sbuko/hLdhyw+D/yNn1XXvak7UGNVvKNHvL\n8a+CxP8D3iqHitkcSEccWhzwnALiljZKl7tFfX/OPouYrPpuhhjHtv8X/y3n\nFpeMVNFXaF1QfwSEMYWNMdL24WUgBr+V5WhRsmi/BCIA+4PtCRk="
+    # MANDRILL_API_KEY
+    - secure: "sjbNGWtWzaPup1yQN+cbtY264NgpNYZrOirVuYj5PMD31emoAiaobS7+cCJH\nx0MUXskjtbzvbJwvzLwkwDpdRA2Hx4dvOKh0HrOVLy1B0bKbVdb7P3eET2aN\nE07nmVNC79jiopD+1pWcbMGXr9s4/sOogK23ktVPegrWH7c0pfI="
+    # SENDGRID_API_USER
+    - secure: "THUH/QdYAVXIFBn24PhcqChMF4XGUzDnzoRxNQMBjVZ3mTM6/dw5lGApx3HQ\nZZy4iUQ0sCWcsPo/tK4AdhZ7/NEcKh/9Uxr1J7GOKBIAJVd5veDe6RCy1eyP\niCmF6QuzVsEgprcxcOPypeybLoUd8TCIhVGPTYaOCamjwx59e3Y="
+    # SENDGRID_API_KEY
+    - secure: "ovfCD7gOOiHteTihQ9YGyUQiSdWrrI15kE2nU8qEfH8suQACBxW4By9D4CY6\ngompkj1svDscXb9u55nbOIH5JWQxM+Uc5OH6vFWBikRdyFPHN0lfsRyUXQj7\nqPkjaEIEAW0Q7bTetdpfTDV1qmCiHALmc2CaexEj9o4JOcN7AeM="

data/README.md

@@ -1,101 +1,243 @@
-# MultiMail: easily switch between email APIs
+# MultiMail: easily switch 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)
 [![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.
+Many providers offer APIs to send, receive, and parse email. MultiMail lets you easily switch between these APIs, and integrates tightly with the [Mail](https://github.com/mikel/mail) gem.
+
+* [Cloudmailin](http://www.cloudmailin.com/): [Example](#cloudmailin)
+* [Mailgun](http://www.mailgun.com/): [Example](#mailgun)
+* [Mandrill](http://mandrill.com/): [Example](#mandrill)
+* [Postmark](http://postmarkapp.com/): [Example](#postmark)
+* [SendGrid](http://sendgrid.com/): [Example](#sendgrid)
 
 ## Usage
 
-    require 'multi_mail'
-    
-    service = MultiMail::Receiver.new(:provider => 'mandrill')
-    
-    message = service.process data # raw POST data or params hash
+### Incoming
 
-`message` is an array of [Mail::Message](https://github.com/mikel/mail) instances.
+```ruby
+require 'multi_mail'
 
-## Supported APIs
+# Create an object to consume the webhook data.
+service = MultiMail::Receiver.new(:provider => 'mandrill')
 
-Incoming email:
+# Process the webhook data, whether it's raw POST data, a params hash, a Rack request, etc.
+messages = service.process(data)
+```
 
-* [Mailgun](http://www.mailgun.com/)
-* [Mandrill](http://mandrill.com/)
-* [Postmark](http://postmarkapp.com/)
-* [Cloudmailin](http://www.cloudmailin.com/)
+`messages` will be an array of [Mail::Message](https://github.com/mikel/mail) instances.
 
-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`.
+Any non-standard parameters provided by an API are added to each 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 as `message['stripped-text'].value`.
 
-## Cloudmailin
+### Outgoing
+
+With MultiMail, you send a message the same way you do with the [Mail](https://github.com/mikel/mail#sending-an-email) gem. Just set `delivery_method`:
+
+```ruby
+require 'multi_mail'
+require 'multi_mail/postmark/sender'
+
+message = Mail.new do
+  delivery_method MultiMail::Sender::Postmark, :api_key => 'your-api-key'
+  ...
+end
+
+message.deliver
+```
+
+Alternatively, instead of setting `delivery_method` during initialization, you can set it before delivery:
+
+```ruby
+message = Mail.new do
+  ...
+end
+
+message.delivery_method MultiMail::Sender::Postmark, :api_key => 'your-api-key'
+
+message.deliver
+```
+
+Or, if you are sending many messages, you can set a default `delivery_method` for all messages:
+
+```ruby
+Mail.defaults do
+  delivery_method MultiMail::Sender::Postmark, :api_key => 'your-api-key'
+end
+```
+
+#### Track opens and clicks
+
+Mailgun and Mandrill allow you to set open tracking and click tracking on a per-message basis:
 
-    service = MultiMail::Receiver.new({
-      :provider => 'cloudmailin',
-    })
+```ruby
+require 'multi_mail'
+require 'multi_mail/mailgun/sender'
 
-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:
+message = Mail.new do
+  delivery_method MultiMail::Sender::Mailgun,
+    :api_key => 'your-api-key',
+    :domain => 'your-domain.mailgun.org',
+    :track => {
+      :opens => true,
+      :clicks => false,
+    }
+  ...
+end
+
+message.deliver
+```
+
+[Mailgun](http://documentation.mailgun.com/user_manual.html#tracking-clicks) and [Mandrill](http://help.mandrill.com/entries/21721852-Why-aren-t-clicks-being-tracked-) track whether a recipient has clicked a link in a message by rewriting its URL.
+
+If want to rewrite URLs in HTML parts only – leaving URLs as-is in text parts – use `:clicks => 'htmlonly'` if you are using Mailgun; if you are using Mandrill, do not set `:clicks` and instead configure click tracking globally in your [Mandrill sending options](https://mandrillapp.com/settings/sending-options).
+
+```ruby
+require 'multi_mail'
+require 'multi_mail/mandrill/sender'
+
+message = Mail.new do
+  delivery_method MultiMail::Sender::Mandrill,
+    :api_key => 'your-api-key',
+    :track => {
+      :opens => true,
+      :clicks => false,
+    }
+  ...
+end
+
+message.deliver
+```
+
+#### Inspect the API response
+
+Pass `:return_response => true` to `delivery_method` and use the `deliver!` method to send the message:
+
+```ruby
+message = Mail.new do
+  delivery_method MultiMail::Sender::Postmark, :api_key => 'your-api-key', :return_response => true
+  ...
+end
+
+message.deliver!
+```
+
+Note that the `deliver!` method ignores Mail's `perform_deliveries` and `raise_delivery_errors` flags.
+
+## Cloudmailin
 
-    service = MultiMail::Receiver.new({
-      :provider => 'cloudmailin',
-      :http_post_format => 'raw',
-    })
+### Incoming
 
-**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.
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'cloudmailin',
+})
+```
 
-**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.
+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):
 
-### Additional information provided by the API
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'cloudmailin',
+  :http_post_format => 'raw',
+})
+```
 
-See [Cloudmailin's documentation](http://docs.cloudmailin.com/http_post_formats/):
+See [Cloudmailin's documentation](http://docs.cloudmailin.com/http_post_formats/) for these additional parameters provided by the API:
 
 * `reply_plain`
 * `spf-result`
 
+**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 default `raw` format).
+
 ## Mailgun
 
-    service = MultiMail::Receiver.new({
-      :provider => 'mailgun',
-      :mailgun_api_key => 'key-xxxxxxxxxxxxxxxxxxxxxxx-x-xxxxxx',
-    })
+### Incoming
+
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'mailgun',
+})
+```
 
-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:
+To check that a request originates from Mailgun, add a `:mailgun_api_key` option:
 
-    service = MultiMail::Receiver.new({
-      :provider => 'mailgun',
-      :mailgun_api_key => 'key-xxxxxxxxxxxxxxxxxxxxxxx-x-xxxxxx',
-      :http_post_format => 'raw',
-    })
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'mailgun',
+  :mailgun_api_key => 'key-xxxxxxxxxxxxxxxxxxxxxxx-x-xxxxxx',
+})
+```
 
-**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.
+If you are using the [raw MIME format](http://documentation.mailgun.com/user_manual.html#mime-messages-parameters), add a `:http_post_format => 'raw'` option:
 
-### Additional information provided by the API
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'mailgun',
+  :http_post_format => 'raw',
+})
+```
 
-See [Mailgun's documentation](http://documentation.mailgun.net/user_manual.html#parsed-messages-parameters):
+See [Mailgun's documentation](http://documentation.mailgun.net/user_manual.html#parsed-messages-parameters) for these additional parameters provided by the API:
 
 * `stripped-text`
 * `stripped-signature`
 * `stripped-html`
 * `content-id-map`
 
+### Outgoing
+
+```ruby
+require 'multi_mail/mailgun/sender'
+
+Mail.deliver do
+  delivery_method MultiMail::Sender::Mailgun, :api_key => 'your-api-key', :domain => 'your-domain.mailgun.org'
+  ...
+end
+```
+
+You may pass additional arguments to `delivery_method` to use Mailgun-specific features ([see docs](http://documentation.mailgun.com/api-sending.html)):
+
+* `o:tag`
+* `o:campaign`
+* `o:dkim`
+* `o:deliverytime`
+* `o:testmode`
+* `o:tracking`
+* `v:`
+
 ## Mandrill
 
-    service = MultiMail::Receiver.new({
-      :provider => 'mandrill',
-    })
+### Incoming
 
-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:
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'mandrill',
+})
+```
 
-    service = MultiMail::Receiver.new({
-      :provider => 'mandrill',
-      :spamassassin_threshold => 4.5,
-    })
+To check that a request originates from Mandrill, add `:mandrill_webhook_key` and `:mandrill_webhook_url` options:
 
-**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.
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'mandrill',
+  :mandrill_webhook_key => 'xxxxxxxxxxxxxxxxxxxxxx',
+  :mandrill_webhook_url => 'http://example.com/post',
+})
+```
+You can get your webhook key from [Mandrill's Webhooks Settings](https://mandrillapp.com/settings/webhooks).
 
-### Additional information provided by the API
+The default SpamAssassin score needed to flag an email as spam is `5`. Add a `:spamassassin_threshold` option to increase or decrease it:
 
-See [Mandrill's documentation](http://help.mandrill.com/entries/22092308-What-is-the-format-of-inbound-email-webhooks-):
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'mandrill',
+  :spamassassin_threshold => 4.5,
+})
+```
+
+See [Mandrill's documentation](http://help.mandrill.com/entries/22092308-What-is-the-format-of-inbound-email-webhooks-) for these additional parameters provided by the API:
 
 * `ts`
 * `email`
@@ -104,22 +246,104 @@ See [Mandrill's documentation](http://help.mandrill.com/entries/22092308-What-is
 * `spam_report-score`
 * `spf-result`
 
-## Postmark
+### Outgoing
+
+```ruby
+require 'multi_mail/mandrill/sender'
+
+Mail.deliver do
+  delivery_method MultiMail::Sender::Mandrill, :api_key => 'your-api-key'
+  ...
+end
+```
+
+You may pass additional arguments to `delivery_method` to use Mandrill-specific features ([see docs](https://mandrillapp.com/api/docs/messages.ruby.html#method-send)):
+
+* `important`
+* `auto_text` and `auto_html`
+* `inline_css`
+* `url_strip_qs`
+* `preserve_recipients`
+* `bcc_address`
+* `tracking_domain` and `signing_domain`
+* `merge`, `global_merge_vars` and `merge_vars`
+* `tags`
+* `google_analytics_domains` and `google_analytics_campaign`
+* `metadata` and `recipient_metadata`
+* `async`
+* `ip_pool`
+* `send_at`
 
-    service = MultiMail::Receiver.new({
-      :provider => 'postmark',
-    })
+## 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.
+### Incoming
 
-### Additional information provided by the API
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'postmark',
+})
+```
 
-See [Postmark's documentation](http://developer.postmarkapp.com/developer-inbound-parse.html#mailboxhash):
+See [Postmark's documentation](http://developer.postmarkapp.com/developer-inbound-parse.html#mailboxhash) for these additional parameters provided by the API:
 
 * `MailboxHash`
 * `MessageID`
 * `Tag`
 
+### Outgoing
+
+```ruby
+require 'multi_mail/postmark/sender'
+
+Mail.deliver do
+  delivery_method MultiMail::Sender::Postmark, :api_key => 'your-api-key'
+  ...
+end
+```
+
+MultiMail depends on the `postmark` gem for its Postmark integration.
+
+You may also pass a `Tag` option to `delivery_method` ([see Postmark's documentation](http://developer.postmarkapp.com/developer-build.html#message-format)).
+
+## SendGrid
+
+### Incoming
+
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'sendgrid',
+})
+```
+
+The default SpamAssassin score needed to flag an email as spam is `5`. Add a `:spamassassin_threshold` option to increase or decrease it:
+
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'sendgrid',
+  :spamassassin_threshold => 4.5,
+})
+```
+
+See [SendGrid's documentation](http://sendgrid.com/docs/API_Reference/Webhooks/parse.html) for these additional parameters provided by the API:
+
+* `dkim`
+* `SPF`
+* `spam_report`
+* `spam_score`
+
+### Outgoing
+
+```ruby
+require 'multi_mail/sendgrid/sender'
+
+Mail.deliver do
+  delivery_method MultiMail::Sender::SendGrid, :api_user => 'username', :api_key => 'password'
+  ...
+end
+```
+
+You may also pass a `x-smtpapi` option to `delivery_method` ([see SendGrid's documentation](http://sendgrid.com/docs/API_Reference/Web_API/mail.html)).
+
 ## 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.

data/Rakefile

@@ -48,17 +48,9 @@ task :mailgun do
   end
 
   if catch_all_route
-    action = catch_all_route['actions'].find do |action|
-      action[%r{\Aforward\("(http://requestb\.in/\w+)"\)\z}]
-    end
-
-    if action
-      bin_url = $1
-    else
-      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
+    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))
   else
     bin_url, action = bin_url_and_action
     puts "Creating a catch_all() route..."
@@ -77,7 +69,7 @@ task :mandrill do
 
   if domain
     domain_name = domain['domain']
-    routes = api.inbound.routes domain_name
+    routes = api.inbound.routes(domain_name)
     match = routes.find{|route| route['pattern'] == '*'}
 
     puts "The MX for #{domain_name} is not valid" unless domain['valid_mx']
@@ -95,18 +87,45 @@ task :postmark do
   require 'rest-client'
 
   api = Postmark::ApiClient.new(credentials[:postmark_api_key])
-
   info = api.server_info
 
-  if info.key?(:inbound_hook_url)
-    url = info[:inbound_hook_url]
+  bin_name = JSON.load(RestClient.post('http://requestb.in/api/v1/bins', {}))['name']
+  url = "http://requestb.in/#{bin_name}"
+  puts "Setting the POST URL..."
+  api.update_server_info :inbound_hook_url => url
+
+  puts "#{info[:inbound_hash]}@inbound.postmarkapp.com POSTs to #{url}?inspect"
+end
+
+desc 'Create a SendGrid route forwarding to a postbin'
+task :sendgrid do
+  require 'json'
+  require 'rest-client'
+  require 'sendgrid_webapi'
+
+  api = SendGridWebApi::Client.new(credentials[:sendgrid_username], credentials[:sendgrid_password])
+  routes = api.parse_email.get['parse']
+
+  if routes.empty? && ENV['DOMAIN'].nil?
+    abort 'usage: DOMAIN=example.com bundle exec rake sendgrid'
+  end
+
+  domain_name = if routes.any?
+    routes.first['hostname']
   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
+    ENV['DOMAIN']
   end
 
-  puts "#{info[:inbound_hash]}@inbound.postmarkapp.com POSTs to #{url}?inspect"
+  bin_name = JSON.load(RestClient.post('http://requestb.in/api/v1/bins', {}))['name']
+  url = "http://requestb.in/#{bin_name}"
+  puts "Setting the POST URL..."
+  result = api.parse_email.set(:hostname => domain_name, :url => url, :spam_check => 0)
+
+  if result['error']
+    puts "HTTP #{result['error']['code']} #{result['error']['message']}"
+  else
+    puts "#{domain_name} POSTs to #{url}?inspect"
+  end
 end
 
 desc 'POST a test fixture to an URL'

data/lib/multi_mail/cloudmailin/receiver.rb

@@ -6,7 +6,7 @@ module MultiMail
     # that a request originates from Cloudmailin.
     #
     # @see http://docs.cloudmailin.com/receiving_email/securing_your_email_url_target/
-    class Cloudmailin < MultiMail::Service
+    class Cloudmailin
       include MultiMail::Receiver::Base
 
       recognizes :http_post_format
@@ -37,21 +37,11 @@ module MultiMail
           # `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`.
+          headers = self.class.multimap(params['headers'])
           http_post_format = @http_post_format
-
           this = self
+
           message = Mail.new do
             headers headers
 

data/lib/multi_mail/mailgun/message.rb

@@ -0,0 +1,67 @@
+module MultiMail
+  module Message
+    # @see http://documentation.mailgun.com/api-sending.html
+    class Mailgun < MultiMail::Message::Base
+      # Returns the message headers in Mailgun format.
+      #
+      # @return [Multimap] the message headers in Mailgun format
+      def mailgun_headers
+        hash = Multimap.new
+        header_fields.each do |field|
+          key = field.name.downcase
+          unless %w(from to cc bcc subject message-id).include?(key)
+            hash["h:#{field.name}"] = field.value
+          end
+        end
+        hash
+      end
+
+      # Returns the message's attachments in Mailgun format.
+      #
+      # @return [Multimap] the attachments in Mailgun format
+      # @see http://documentation.mailgun.com/user_manual.html#inline-image
+      def mailgun_attachments
+        hash = Multimap.new
+        attachments.each do |attachment|
+          key = attachment.content_type.start_with?('image/') ? 'inline' : 'attachment'
+          hash[key] = Faraday::UploadIO.new(StringIO.new(attachment.body.decoded), attachment.content_type, attachment.filename)
+        end
+        hash
+      end
+
+      # Returns the message as parameters to POST to Mailgun.
+      #
+      # @return [Hash] the message as parameters to POST to Mailgun
+      def to_mailgun_hash
+        hash = Multimap.new
+
+        %w(from subject).each do |field|
+          if self[field]
+            hash[field] = self[field].value
+          end
+        end
+
+        %w(to cc bcc).each do |field|
+          if self[field]
+            if self[field].value.respond_to?(:each)
+              self[field].value.each do |value|
+                hash[field] = value
+              end
+            else
+              hash[field] = self[field].value
+            end
+          end
+        end
+
+        if body_text && !body_text.empty?
+          hash['text'] = body_text
+        end
+        if body_html && !body_html.empty?
+          hash['html'] = body_html
+        end
+
+        normalize(hash.merge(mailgun_attachments).merge(mailgun_headers).to_hash)
+      end
+    end
+  end
+end