multi_mail 0.1.0 → 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 10a52d2bbde07c200870939a097077677734ec7f
+  data.tar.gz: 41aeb775d3c1cf6b1fefb20799756a78297eecbb
+SHA512:
+  metadata.gz: ea709588481915a7bc64e7402eb1dffc43ddfc470f0f79e7417f17c594fb29b73721953c1d1364117e5e3ac2201a8526fb3cf168ecb58e60a3c4529a33cc33af
+  data.tar.gz: 2a2bf5311c4098c2255ab698fcd5c6498350d2adb601b1d8aff2de79dcc5683b45ea2d9a157961b3f5153ad729cf61c1d5b4b100a0204ca3b62fbb1f07242c43

data/README.md

@@ -12,6 +12,7 @@ Many providers offer APIs to send, receive, and parse email. MultiMail lets you
 * [Mandrill](http://mandrill.com/): [Example](#mandrill)
 * [Postmark](http://postmarkapp.com/): [Example](#postmark)
 * [SendGrid](http://sendgrid.com/): [Example](#sendgrid)
+* MTA like [Postfix](http://en.wikipedia.org/wiki/Postfix_\(software\)) or [qmail](http://en.wikipedia.org/wiki/Qmail): [Example](#mta)
 
 ## Usage
 
@@ -37,7 +38,6 @@ With MultiMail, you send a message the same way you do with the [Mail](https://g
 
 ```ruby
 require 'multi_mail'
-require 'multi_mail/postmark/sender'
 
 message = Mail.new do
   delivery_method MultiMail::Sender::Postmark, :api_key => 'your-api-key'
@@ -67,39 +67,38 @@ Mail.defaults do
 end
 ```
 
-#### Track opens and clicks
+#### Tagging
 
-Mailgun and Mandrill allow you to set open tracking and click tracking on a per-message basis:
+Mailgun, Mandrill and Postmark allow you to tag messages in order to accumulate statistics by tag, which will be accessible through their user interface:
 
 ```ruby
 require 'multi_mail'
-require 'multi_mail/mailgun/sender'
 
 message = Mail.new do
-  delivery_method MultiMail::Sender::Mailgun,
-    :api_key => 'your-api-key',
-    :domain => 'your-domain.mailgun.org',
-    :track => {
-      :opens => true,
-      :clicks => false,
-    }
+  delivery_method MultiMail::Sender::Mandrill, :api_key => 'your-api-key'
+
+  tag 'signup'
+  tag 'promotion'
+
   ...
 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.
+Mailgun accepts at most [3 tags](http://documentation.mailgun.com/user_manual.html#tagging) and Postmark at most one tag.
 
-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).
+#### Track opens and clicks
+
+Mailgun and Mandrill allow you to set open tracking and click tracking on a per-message basis:
 
 ```ruby
 require 'multi_mail'
-require 'multi_mail/mandrill/sender'
 
 message = Mail.new do
-  delivery_method MultiMail::Sender::Mandrill,
+  delivery_method MultiMail::Sender::Mailgun,
     :api_key => 'your-api-key',
+    :domain => 'your-domain.mailgun.org',
     :track => {
       :opens => true,
       :clicks => false,
@@ -110,6 +109,8 @@ 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).
+
 #### Inspect the API response
 
 Pass `:return_response => true` to `delivery_method` and use the `deliver!` method to send the message:
@@ -144,13 +145,21 @@ service = MultiMail::Receiver.new({
 })
 ```
 
+If you are using an [Amazon S3 attachment store](http://docs.cloudmailin.com/receiving_email/attachments/), add a `:attachment_store => true` option. You must set the attachment store's permission setting to "Public Read".
+
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'cloudmailin',
+  :http_post_format => 'multipart',
+  :attachment_store => true,
+})
+```
+
 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
 
 ### Incoming
@@ -189,8 +198,6 @@ See [Mailgun's documentation](http://documentation.mailgun.net/user_manual.html#
 ### 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'
   ...
@@ -199,7 +206,6 @@ 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`
@@ -217,7 +223,7 @@ service = MultiMail::Receiver.new({
 })
 ```
 
-To check that a request originates from Mandrill, add `:mandrill_webhook_key` and `:mandrill_webhook_url` options:
+To check that a request originates from Mandrill, add `:mandrill_webhook_key` and `:mandrill_webhook_url` options (you can get your webhook key from [Mandrill's Webhooks Settings](https://mandrillapp.com/settings/webhooks)):
 
 ```ruby
 service = MultiMail::Receiver.new({
@@ -226,7 +232,6 @@ service = MultiMail::Receiver.new({
   :mandrill_webhook_url => 'http://example.com/post',
 })
 ```
-You can get your webhook key from [Mandrill's Webhooks Settings](https://mandrillapp.com/settings/webhooks).
 
 The default SpamAssassin score needed to flag an email as spam is `5`. Add a `:spamassassin_threshold` option to increase or decrease it:
 
@@ -249,8 +254,6 @@ See [Mandrill's documentation](http://help.mandrill.com/entries/22092308-What-is
 ### Outgoing
 
 ```ruby
-require 'multi_mail/mandrill/sender'
-
 Mail.deliver do
   delivery_method MultiMail::Sender::Mandrill, :api_key => 'your-api-key'
   ...
@@ -267,7 +270,6 @@ You may pass additional arguments to `delivery_method` to use Mandrill-specific
 * `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`
@@ -287,24 +289,17 @@ service = MultiMail::Receiver.new({
 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
@@ -334,8 +329,6 @@ See [SendGrid's documentation](http://sendgrid.com/docs/API_Reference/Webhooks/p
 ### Outgoing
 
 ```ruby
-require 'multi_mail/sendgrid/sender'
-
 Mail.deliver do
   delivery_method MultiMail::Sender::SendGrid, :api_user => 'username', :api_key => 'password'
   ...
@@ -344,6 +337,36 @@ 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)).
 
+## MTA
+
+### Incoming
+
+If you are switching from an email API to Postfix or qmail, the simplest option is to continue sending messages to your application's webhook URL.
+
+Your Postfix configuration may look like:
+
+    # /etc/postfix/virtual
+    incoming@myapp.com myappalias
+
+    # /etc/mail/aliases
+    myappalias: "| multi_mail_post --secret my-secret-string http://www.myapp.com/post"
+
+Your qmail configuration may look like:
+
+    # /var/qmail/mailnames/myapp.com/.qmail-incoming
+    | multi_mail_post --secret my-secret-string http://www.myapp.com/post
+
+In your application, you would use the `simple` provider:
+
+```ruby
+service = MultiMail::Receiver.new({
+  :provider => 'simple',
+  :secret => 'my-secret-string',
+})
+```
+
+It's recommended to use a secret key, to ensure that the requests are sent by Postfix and qmail and not by other sources on the internet.
+
 ## 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/bin/multi_mail_post

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'securerandom'
+
+require 'multi_mail'
+require 'multi_mail/version'
+
+secret = nil
+
+opts = OptionParser.new do |opts|
+  opts.banner = "Usage: #{opts.program_name} [options] URL < INPUT"
+  opts.on('-s', '--secret SECRET', 'A secret key to ensure that requests are authentic') do |v|
+    secret = v
+  end
+  opts.on_tail('-h', '--help', 'Show this message') do
+    puts opts
+    exit
+  end
+  opts.on_tail('-v', '--version', 'Show version') do
+    puts MultiMail::VERSION
+    exit
+  end
+end
+
+rest = opts.parse!(ARGV)
+
+if rest.empty?
+  puts opts.banner
+  exit
+end
+
+url = rest.shift
+
+begin
+  url = URI.parse(url)
+rescue URI::InvalidURIError
+  abort "#{url} is not a valid URI"
+end
+
+unless url.scheme && url.host
+  abort "#{url} is not a valid URI"
+end
+
+service = MultiMail::Receiver.new({
+  :provider => :simple,
+  :secret => secret,
+})
+
+params = {
+  'message' => STDIN.read,
+  'timestamp' => Time.now.to_i,
+  'token' => SecureRandom.hash,
+}
+
+params['signature'] = service.signature(params) if secret
+
+connection = Faraday.new(:url => "#{url.scheme}://#{url.host}:#{url.port}") do |conn|
+  conn.basic_auth url.user, url.password if url.user || url.password
+  conn.request :url_encoded
+  conn.adapter Faraday.default_adapter
+end
+
+response = connection.post(url.path, params)
+
+if response.status != 200
+  headers = response.headers.map do |key,value|
+    "#{key.gsub(/\b([a-z])/) {$1.capitalize}}: #{value}"
+  end
+  abort (headers + ['', response.body]).join("\r\n")
+end

data/lib/mail_ext/message.rb

@@ -0,0 +1,11 @@
+module Mail
+  class Message
+    def tag(val = nil)
+      default :tag, val
+    end
+
+    def tag=(val)
+      header[:tag] = val
+    end
+  end
+end

data/lib/multi_mail.rb

@@ -9,24 +9,33 @@ require 'mail'
 require 'multimap'
 require 'rack'
 
+require 'mail_ext/message'
+
 module MultiMail
   # @see http://rdoc.info/gems/fog/Fog/Errors
   class Error < StandardError; end
+
   # Raise if an incoming POST request is forged.
   class ForgedRequest < MultiMail::Error; end
-  # Raise if an API key is invalid.
-  class InvalidAPIKey < MultiMail::Error; end
 
+  # Raise if an outgoing request is invalid.
+  class InvalidRequest < MultiMail::Error; end
+  # Raise if an API key is invalid.
+  class InvalidAPIKey < InvalidRequest; end
   # Raise if a message is invalid.
-  class InvalidMessage < MultiMail::Error; end
+  class InvalidMessage < InvalidRequest; end
+
+  # Raise if a message header is invalid
+  class InvalidHeader < InvalidMessage; end
+  # Raise if a message has no body.
+  class MissingBody < InvalidMessage; end
+
   # Raise if a message has no sender.
-  class MissingSender < InvalidMessage; end
+  class MissingSender < InvalidHeader; end
   # Raise if a message has no recipients.
-  class MissingRecipients < InvalidMessage; end
+  class MissingRecipients < InvalidHeader; end
   # Raise if a message has no subject.
-  class MissingSubject < InvalidMessage; end
-  # Raise if a message has no body.
-  class MissingBody < InvalidMessage; end
+  class MissingSubject < InvalidHeader; end
 
   class << self
     # @return [RegExp] a message whose subject matches this pattern will be
@@ -97,3 +106,11 @@ require 'multi_mail/receiver'
 require 'multi_mail/message/base'
 require 'multi_mail/receiver/base'
 require 'multi_mail/sender/base'
+require 'multi_mail/mailgun/message'
+require 'multi_mail/mailgun/sender'
+require 'multi_mail/mandrill/message'
+require 'multi_mail/mandrill/sender'
+require 'multi_mail/postmark/message'
+require 'multi_mail/postmark/sender'
+require 'multi_mail/sendgrid/message'
+require 'multi_mail/sendgrid/sender'

data/lib/multi_mail/cloudmailin/receiver.rb

@@ -9,15 +9,18 @@ module MultiMail
     class Cloudmailin
       include MultiMail::Receiver::Base
 
-      recognizes :http_post_format
+      recognizes :http_post_format, :attachment_store
 
       # Initializes a Cloudmailin incoming email receiver.
       #
       # @param [Hash] options required and optional arguments
       # @option options [String] :http_post_format "multipart", "json" or "raw"
+      # @option options [Boolean] :attachment_store whether attachments have
+      #   been sent to an attachment store
       def initialize(options = {})
         super
         @http_post_format = options[:http_post_format]
+        @attachment_store = options[:attachment_store]
       end
 
       # @param [Hash] params the content of Cloudmailin's webhook
@@ -33,6 +36,12 @@ module MultiMail
           # Extra Cloudmailin parameters.
           message['spf-result'] = params['envelope']['spf']['result']
 
+          if @attachment_store
+            params['attachments'].each do |_,attachment|
+              message.add_file(:filename => attachment['file_name'], :content => Faraday.get(attachment['url']).body)
+            end
+          end
+
           # Discard rest of `envelope`: `from`, `to`, `recipients`,
           # `helo_domain` and `remote_ip`.
           [message]
@@ -40,6 +49,7 @@ module MultiMail
           # Mail changes `self`.
           headers = self.class.multimap(params['headers'])
           http_post_format = @http_post_format
+          attachment_store = @attachment_store
           this = self
 
           message = Mail.new do
@@ -57,13 +67,24 @@ module MultiMail
             end
 
             if params.key?('attachments')
+              # Using something like lazy.rb will not prevent the HTTP request,
+              # because the Mail gem must be able to call #valid_encoding? on
+              # the attachment body (in Ruby 1.9).
               if http_post_format == 'json'
                 params['attachments'].each do |attachment|
-                  add_file(:filename => attachment['file_name'], :content => Base64.decode64(attachment['content']))
+                  if attachment_store
+                    add_file(:filename => attachment['file_name'], :content => Faraday.get(attachment['url']).body)
+                  else
+                    add_file(:filename => attachment['file_name'], :content => Base64.decode64(attachment['content']))
+                  end
                 end
               else
                 params['attachments'].each do |_,attachment|
-                  add_file(this.class.add_file_arguments(attachment))
+                  if attachment_store
+                    add_file(:filename => attachment['file_name'], :content => Faraday.get(attachment['url']).body)
+                  else
+                    add_file(this.class.add_file_arguments(attachment))
+                  end
                 end
               end
             end

data/lib/multi_mail/mailgun/message.rb

@@ -9,7 +9,7 @@ module MultiMail
         hash = Multimap.new
         header_fields.each do |field|
           key = field.name.downcase
-          unless %w(from to cc bcc subject message-id).include?(key)
+          unless %w(from to cc bcc subject tag).include?(key)
             hash["h:#{field.name}"] = field.value
           end
         end
@@ -32,6 +32,7 @@ module MultiMail
       # Returns the message as parameters to POST to Mailgun.
       #
       # @return [Hash] the message as parameters to POST to Mailgun
+      # @see http://documentation.mailgun.com/user_manual.html#tagging
       def to_mailgun_hash
         hash = Multimap.new
 
@@ -60,6 +61,10 @@ module MultiMail
           hash['html'] = body_html
         end
 
+        tags.each do |tag|
+          hash['o:tag'] = tag
+        end
+
         normalize(hash.merge(mailgun_attachments).merge(mailgun_headers).to_hash)
       end
     end