mandrails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 232ca2cd61971d639dff8c2a880335c979b218f7
+  data.tar.gz: a5a4a0d3ec3c9d0ee8283281f80710cd28a1fcb6
+SHA512:
+  metadata.gz: 3c02696ceff66b20285ae3309edd86f6a91841fe81e63920cb98604e80281cbe6d54a579ec25fd3f8b31862a198aee9138b88daa94310dbd9a0fba7328c945ba
+  data.tar.gz: a54f6b7599bc5f7fb4da2fea9624304f8842d4ee310bfb6dbed84751c9f1501b439f64aa5d48c5c9a39c27a53d815903fedbc2e9326d978d944ddc04b8416e36

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mandrails.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013,2014 at-point ag. http://at-point.ch
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,56 @@
+# Mandrails - The Mandrill/ActionMailer connector
+
+A delivery method implementation which uses the Mandrill REST API. This allows
+to simply send e-mails from a Rails app using Mandrill instead of SMTP or
+sendmail.
+
+### Open items
+
+Currently this gem is in alpha quality, things we are still working:
+
+- [ ] Support for custom `X-` headers
+- [ ] Ability to override Mandrill settings, e.g. click tracking, per mail
+- [x] <del>Improve test cases</del>
+- [x] <del>Implement Railtie which automatically hooks delivery method into AM</del>
+- [x] <del>Attachment support</del>
+
+## Installation
+
+Add mandrails to your Gemfile and run `bundle` afterwards:
+
+```ruby
+    gem 'mandrails'
+```
+
+## Usage
+
+When using with Rails it's basically all setup to use the `:mandrill` delivery
+handler in config/environemnts/*.rb:
+
+```ruby
+  config.action_mailer.delivery_method = :mandrill
+  config.action_mailer.mandrill_settings = {
+    key: "123...-abcde", # or set the MANDRILL_APIKEY environment variable
+    from_name: "My Application",
+    from_email: "saas@example.com"
+  }
+```
+
+Basically the `:key` and `:from_email` are required attributes, the `:key` can
+be omitted if the `MANDRILL_APIKEY` environment variable is set.
+
+## Additional information
+
+### Mailchimp & Mandrill
+
+Thanks to the team at [Mailchimp][mc] which provides the [mandrill-api gem][gem]
+and of course the [Mandrill service][ma] itself. FYI - the maintainers of this
+gem are in no way affiliated with Mailchimp or Mandrill.
+
+## License
+
+MIT License. Copyright 2013 at-point ag. http://at-point.ch
+
+[mc]: http://mailchimp.com/
+[gem]: https://bitbucket.org/mailchimp/mandrill-api-ruby/
+[ma]: https://mandrillapp.com/

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/mandrails.rb

@@ -0,0 +1,4 @@
+require "mandrails/version"
+require "mandrails/delivery/mandrill"
+
+require "mandrails/railtie" if defined?(::Rails)

data/lib/mandrails/delivery/mandrill.rb

@@ -0,0 +1,75 @@
+require "mail"
+require "mandrill"
+
+require "mandrails/message_builder"
+
+module Mandrails
+  module Delivery
+
+    # == Sending e-mail with Mandrill API
+    #
+    # A delivery method implementation which uses the Mandrill REST API.
+    # This is done by providing a mailer on top of mandrill-api gem.
+    #
+    # === Using it with mail gem
+    #
+    # Requires the <code>:key</code> option, or set the environment
+    # variable <code>MANDRILL_APIKEY</code> to a your Mandrill API key.
+    #
+    #   Mail.defaults do
+    #     delivery_method Mandrails::Delivery::Mandrill, {
+    #                              :key        => "123...-abcde", # or set the MANDRILL_APIKEY environment variable
+    #                              :from_name  => "Your Name",
+    #                              :from_email => "your@mail.com" }
+    #   end
+    #
+    # === Using it with Rails & ActionMailer
+    #
+    # Using the railtie the <code>:mandrill</code> delivery method is
+    # automatically available, also ensure to set the API key using
+    # either <code>:key</code> setting or <code>MANDRILL_APIKEY</code>
+    # environment variable. Add something like to the <code>config/environments/*</code>:
+    #
+    #    config.action_mailer.delivery_method = :mandrill
+    #    config.action_mailer.mandrails_settings = {
+    #      key: "123...-abcde", # or set the MANDRILL_APIKEY environment variable
+    #      from_name: "Your Name",
+    #      from_email: "your@mail.com" }
+    #
+    class Mandrill
+
+      # Provide read/write access, dunno why write access is required,
+      # but seems to be in all deliver_methods from mikel/mail as well
+      attr_accessor :settings
+
+      def initialize(values = nil) #:nodoc:
+        @settings = {
+                      track_opens: true,
+                      track_clicks: false,
+                      auto_text: true,
+                      merge: false,
+                      async: false,
+                      key: ::ENV['MANDRILL_APIKEY'].presence
+                    }.merge(values || {})
+      end
+
+      # Public: Access to the Mandrill::API instance used to send messages. It raises an
+      # error if no key was given or is present.
+      #
+      # Returns Mandrill::API instance.
+      def mandrill_api
+        @mandrill_api ||= ::Mandrill::API.new(settings[:key].presence)
+      end
+
+      def deliver!(mail)
+        # TODO: verify incoming `mail` argument, see https://github.com/mikel/mail/blob/master/lib/mail/check_delivery_params.rb
+        builder = Mandrails::MessageBuilder.new mail, settings
+        response = mandrill_api.messages.send(builder.as_json, settings[:async])
+
+        # Either return response or instance
+        return response if settings[:return_response]
+        self
+      end
+    end
+  end
+end

data/lib/mandrails/message_builder.rb

@@ -0,0 +1,100 @@
+require 'active_support/core_ext/object'
+require 'base64'
+
+module Mandrails
+
+  # The MessageBuilder is used to convert a Mail::Message into a JSON object
+  # consumable by the Mandrill API.
+  class MessageBuilder
+
+    # Setting keys which are not allowed to by set by the message
+    RESTRICTED_KEYS = %w{key async}
+
+    # Known mandrill settings
+    MANDRILL_SETTINGS = [:track_opens, :track_clicks, :auto_text,
+      :url_strip_qs, :preserve_recipients, :bcc_address]
+
+    # Access to mail and defaults
+    attr_reader :mail, :defaults
+
+    # Public:
+    #
+    def initialize(mail, defaults = {})
+      @mail = mail
+      @defaults = defaults.reject { |key, value| RESTRICTED_KEYS.include?(key.to_s) }
+    end
+
+    def message
+      @message ||= defaults.merge(
+        # E-Mail stuff
+        html: body(:html),
+        text: body(:text),
+        subject: mail.subject,
+        from_email: from_email,
+        from_name: from_name,
+        to: recipients,
+
+        # Additional headers
+        attachments: attachments,
+        headers: headers)
+    end
+
+    # Internal: Extract from name from either the header or defaults.
+    #
+    # Returns String.
+    def from_name
+      mail.header['from-name'].to_s.presence || defaults[:from_name]
+    end
+
+    # Internal: Extract from email.
+    #
+    # Returns String
+    def from_email
+      mail.from && mail.from.first.presence || defaults[:from_email]
+    end
+
+    # Internal: Extract body of specified format, if any.
+    #
+    # Returns String or nil.
+    def body(format)
+      content = mail.send("#{format}_part").presence
+      content ||= mail if mail.mime_type =~ %r{\Atext/#{format}} || format == :text && text?
+      content.body.raw_source if content.present?
+    end
+
+    def text?
+      mail.mime_type =~ %r{\Atext/plain} || !mail.mime_type
+    end
+
+    # Internal: Build recipients list.
+    #
+    # Returns Array of Hash with `:name`, `:email`.
+    def recipients
+      [mail.to, mail.cc].compact.flatten.map { |email| { email: email, name: email } }
+    end
+
+    # Internal: Extract attachments.
+    #
+    # Returns Array of Hash.
+    def attachments
+      return unless mail.attachments.length > 0
+      mail.attachments.map do |part|
+        { type: part.mime_type, name: part.filename, content: Base64.encode64(part.body.raw_source).strip }
+      end
+    end
+
+    # Internal: Extract Reply-To header field.
+    # FIXME: extract all X-* headers as well!
+    #
+    # Returns Hash.
+    def headers
+      headers = {}
+      headers['Reply-To'] = mail.reply_to.first.to_s if mail.reply_to.present?
+      headers
+    end
+
+    def as_json
+      message
+    end
+  end
+end

data/lib/mandrails/railtie.rb

@@ -0,0 +1,11 @@
+require 'rails'
+
+module Mandrails
+  class Railtie < Rails::Railtie #:nodoc:
+    initializer 'mandrails.setup_action_mailer', before: 'action_mailer.set_configs' do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :mandrill, Mandrails::Delivery::Mandrill
+      end
+    end
+  end
+end

data/lib/mandrails/version.rb

@@ -0,0 +1,3 @@
+module Mandrails
+  VERSION = "1.0.0"
+end

data/mandrails.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/mandrails/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "mandrails"
+  gem.version       = Mandrails::VERSION
+  gem.authors       = ["Lukas Westermann", "Philip Lehmann"]
+  gem.email         = ["lukas@at-point.ch", "philip@at-point.ch"]
+  gem.summary       = %q{An e-mail delivery method implementation which uses the Mandrill REST API.}
+  gem.description   = %q{Provides a delivery method implementation for ActionMailer and mail which uses the Mandrill REST API.}
+  gem.homepage      = "https://github.com/at-point/mandrails"
+
+  gem.files         = %w{.gitignore Gemfile Rakefile README.md LICENSE.txt mandrails.gemspec} + Dir['{lib,spec}/**/*.rb']
+  gem.test_files    = Dir['spec/**/*.rb']
+  gem.require_paths = ["lib"]
+
+  gem.required_ruby_version = '>= 1.9'
+
+  gem.add_dependency 'mail', '>= 2.0'
+  gem.add_dependency 'activesupport', '>= 4.0.0'
+  gem.add_dependency 'mandrill-api', '>= 1.0'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec', '~> 2.12'
+  gem.add_development_dependency 'actionmailer', '>= 4.0.0'
+end

data/spec/factories.rb

@@ -0,0 +1,50 @@
+require 'mail'
+
+module Factories
+  module Emails
+    def text_mail
+      @text_mail ||= Mail.new do
+        from 'mila@fox.com'
+        to 'megan@fox.com'
+        subject 'Hi'
+        body 'Yoo buddy'
+      end
+    end
+
+    def html_mail
+      @html_mail ||= Mail.new do
+        to 'megan@fox.com'
+        content_type 'text/html'
+        body '<b>Yoo</b> buddy'
+      end
+    end
+
+    def multipart_mail
+      @multipart_mail ||= Mail.new do
+        to 'megan@fox.com'
+        text_part { body 'Yoo buddy' }
+        html_part { body '<b>Yoo</b> buddy' }
+      end
+    end
+
+    def cc_mail
+      @cc_mail ||= begin
+        text_mail[:to] = 'Megan <megan@fox.com>'
+        text_mail[:cc] = 'Mila <mila@fox.com>'
+        text_mail[:bcc] = 'Emma <emma@fox.com>'
+        text_mail
+      end
+    end
+
+    def attachment_mail
+      @attachment_mail ||= Mail.new do
+        to 'megan@fox.com'
+        subject 'Hi'
+        body 'Yooo with attachment'
+
+        attachments['file.pdf'] = { mime_type: 'application/pdf', content: 'PDF FILE BRO!' }
+        attachments['other.csv'] = { mime_type: 'text/csv', content: "A,B,C\n1,2,3\n" }
+      end
+    end
+  end
+end

data/spec/mandrails/delivery/mandrill_spec.rb

@@ -0,0 +1,62 @@
+require 'spec_helper'
+require 'mandrails/delivery/mandrill'
+
+describe Mandrails::Delivery::Mandrill do
+  include Factories::Emails
+
+  subject { described_class.new(key: "12345") }
+
+  let(:messages) {
+    double("messages").tap { |msg| subject.mandrill_api.stub(:messages) { msg } }
+  }
+
+  context ':key' do
+    it 'raises an exception if missing' do
+      handler = described_class.new(key: nil)
+      expect { handler.deliver!(text_mail) }.to raise_error ::Mandrill::Error, /Mandrill API key/
+    end
+
+    it 'is forwarded to mandrill gem as key when creating API instance' do
+      subject.mandrill_api.apikey.should == "12345"
+    end
+  end
+
+  context '#deliver!' do
+    it 'delegates message to mandrill gem' do
+      messages.should_receive(:send).with(kind_of(Hash), false) { "OK" }
+      subject.deliver! text_mail
+    end
+
+    context 'async' do
+      it 'normally does not send async' do
+        messages.should_receive(:send).with(kind_of(Hash), false) { "OK" }
+        subject.deliver! text_mail
+      end
+
+      context 'when :async is true' do
+        subject { described_class.new(key: '12345', async: true) }
+
+        it 'defaults to sending async' do
+        messages.should_receive(:send).with(kind_of(Hash), true) { "OK" }
+        subject.deliver! text_mail
+        end
+      end
+    end
+
+    context 'return value' do
+      it 'normally returns self' do
+        messages.should_receive(:send) { "OK" }
+        subject.deliver!(text_mail).should eql subject
+      end
+
+      context 'when :return_response is true' do
+        subject { described_class.new(key: '12345', return_response: true) }
+
+        it 'returns the response 1:1 as returned by the mandrill gem' do
+          messages.should_receive(:send) { "TEH result" }
+          subject.deliver!(text_mail).should == "TEH result"
+        end
+      end
+    end
+  end
+end

data/spec/mandrails/message_builder_spec.rb

@@ -0,0 +1,115 @@
+require 'spec_helper'
+require 'mail'
+require 'mandrails/message_builder'
+
+describe Mandrails::MessageBuilder do
+  include Factories::Emails
+
+  subject { described_class.new(text_mail).as_json }
+
+  context 'subject' do
+    it 'sets :subject' do
+      subject[:subject].should == 'Hi'
+    end
+  end
+
+  context 'recipients' do
+    it 'sets :to Array' do
+      subject[:to].should == [{ email: "megan@fox.com", name: "megan@fox.com" }]
+    end
+
+    context 'To, Cc & Bcc' do
+      subject { described_class.new(cc_mail).as_json }
+
+      it 'sets :to by combining To & Cc' do
+        subject[:to].should == [{ email: "megan@fox.com", name: "megan@fox.com" }, { email: "mila@fox.com", name: "mila@fox.com" }]
+      end
+    end
+  end
+
+  context 'from' do
+    it 'sets :from_email and :from_name' do
+      subject[:from_email].should == 'mila@fox.com'
+      subject[:from_name].should be_nil
+    end
+
+    it 'sets :from_name based on header' do
+      text_mail[:from_name] = 'Mila'
+      subject[:from_name].should == 'Mila'
+    end
+
+    context 'with default from_name & from_email' do
+      subject { described_class.new(text_mail, from_name: "App", from_mail: "app@fox.com").as_json }
+
+      it 'sets :from_name from default' do
+        subject[:from_name].should == 'App'
+      end
+    end
+  end
+
+  context 'body' do
+    context 'text only mail' do
+      subject { described_class.new(text_mail).as_json }
+
+      it 'sets :html key to nil' do
+        subject[:html].should be_nil
+      end
+
+      it 'sets :text' do
+        subject[:text].should == 'Yoo buddy'
+      end
+    end
+
+    context 'html only mail' do
+      subject { described_class.new(html_mail).as_json }
+
+      it 'sets :html' do
+        subject[:html].should == '<b>Yoo</b> buddy'
+      end
+
+      it 'sets :text to nil' do
+        subject[:text].should be_nil
+      end
+    end
+
+    context 'multipart mail' do
+      subject { described_class.new(multipart_mail).as_json }
+
+      it 'sets :html' do
+        subject[:html].should == '<b>Yoo</b> buddy'
+      end
+
+      it 'sets :text' do
+        subject[:text].should == 'Yoo buddy'
+      end
+    end
+  end
+
+  context 'attachments' do
+    subject { described_class.new(attachment_mail).as_json }
+
+    it 'sets :text' do
+      subject[:text].should == 'Yooo with attachment'
+    end
+
+    it 'has two attachments' do
+      subject[:attachments].length.should == 2
+    end
+
+    context 'first attachment (pdf)' do
+      subject { described_class.new(attachment_mail).as_json[:attachments].first }
+
+      it 'has :type as application/pdf' do
+        subject[:type].should == 'application/pdf'
+      end
+
+      it 'has :name' do
+        subject[:name].should == 'file.pdf'
+      end
+
+      it 'has Base64 encoded :content' do
+        subject[:content].should == 'UERGIEZJTEUgQlJPIQ=='
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'rspec'
+require 'factories'

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: mandrails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Lukas Westermann
+- Philip Lehmann
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: mandrill-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+description: Provides a delivery method implementation for ActionMailer and mail which
+  uses the Mandrill REST API.
+email:
+- lukas@at-point.ch
+- philip@at-point.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/mandrails.rb
+- lib/mandrails/delivery/mandrill.rb
+- lib/mandrails/message_builder.rb
+- lib/mandrails/railtie.rb
+- lib/mandrails/version.rb
+- mandrails.gemspec
+- spec/factories.rb
+- spec/mandrails/delivery/mandrill_spec.rb
+- spec/mandrails/message_builder_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/at-point/mandrails
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '1.9'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: An e-mail delivery method implementation which uses the Mandrill REST API.
+test_files:
+- spec/factories.rb
+- spec/mandrails/delivery/mandrill_spec.rb
+- spec/mandrails/message_builder_spec.rb
+- spec/spec_helper.rb