mandrill_mailer 0.0.1

data/.gitignore

@@ -0,0 +1 @@
+mandrill_mailer-0.0.1.gem

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,110 @@
+# Mandrill Mailer gem
+MandrilMailer class for sending transactional emails through mandril.
+Only template based emails are supported at this time.
+
+## Usage
+Add `gem 'mandrill_mailer'` to your Gemfile
+
+Add this to your `mail.rb` in initializers:
+
+```
+ActionMailer::Base.smtp_settings = {
+    :address   => "smtp.mandrillapp.com",
+    :port      => 587,
+    :user_name => ENV['MANDRILL_USERNAME'],
+    :password  => ENV['MANDRILL_PASSWORD'],
+    :domain    => 'heroku.com'
+  }
+ActionMailer::Base.delivery_method = :smtp
+MandrillMailer.api_key = ENV['MANDRILL_API_KEY']
+```
+
+Don't forget to setup your ENV variables on your server
+
+## Creating a new mailer
+Creating a new Mandrill Mailer is similar to a normal Rails mailer:
+
+```
+ class InvitationMailer < MandrillMailer
+   default from: 'support@example.com'
+
+   def invite(invitation)
+     mandrill_mail template: 'Group Invite',
+       subject: I18n.t('invitation_mailer.invite.subject'),
+       to: {email: invitation.email, name: 'Honored Guest'},
+       vars: {
+         'OWNER_NAME' => invitation.owner_name,
+         'INVITATION_URL' => new_invitation_url(email: invitation.email, secret: invitation.secret)
+       }
+   end
+ end
+ ```
+
+ * `#default:`
+  * `:from` - set the default from email address for the mailer
+
+* `.mandrill_mail`
+   * `:template`(required) - Template name from within Mandrill
+
+   * `:subject`(required) - Subject of the email
+
+   * `:to`(required) - Accepts an email String, or hash with :name and :email keys
+     ex. `{email: 'someone@email.com', name: 'Bob Bertly'}`
+
+   * `:vars` - A Hash of merge tags made available to the email. Use them in the
+     email by wrapping them in `*||*` vars: {'OWNER_NAME' => 'Suzy'} is used
+     by doing: `*|OWNER_NAME|*` in the email template within Mandrill
+
+   * `:template_content` - A Hash of values and content for Mandrill editable content blocks.
+     In MailChimp templates there are editable regions with 'mc:edit' attributes that look
+     a little like: `<div mc:edit="header">My email content</div>` You can insert content directly into
+     these fields by passing a Hash `{'header' => 'my email content'}`
+
+   * `:headers` - Extra headers to add to the message (currently only Reply-To and X-* headers are allowed) {"...": "..."}
+
+   * `:bcc` - Add an email to bcc to
+
+   * `:tags` - Array of Strings to tag the message with. Stats are
+   accumulated using tags, though we only store the first 100 we see,
+   so this should not be unique or change frequently. Tags should be
+   50 characters or less. Any tags starting with an underscore are
+   reserved for internal use and will cause errors.
+
+   * `:google_analytics_domains` - Array of Strings indicating for which any
+   matching URLs will automatically have Google Analytics parameters appended
+   to their query string automatically.
+
+   * `:google_analytics_campaign` - String indicating the value to set for
+   the utm_campaign tracking parameter. If this isn't provided the email's
+   from address will be used instead.
+   
+## Sending an email
+
+You can send the email by using the familiar syntax:
+
+`InvitationMailer.invite(invitation).deliver`
+   
+## Creating a test method
+When switching over to Mandrill for transactional emails we found that it was hard to setup a mailer in the console to send test emails easily (those darn designers), but really, you don't want to have to setup test objects everytime you want to send a test email. You can set up a testing 'stub' once and then call the `.test` method to send the test email.
+
+You can test the above email by typing: `InvitationMailer.test(:invite, email:<your email>)` into the Rails Console.
+
+The test for this particular Mailer is setup like so:
+
+```
+test_setup_for :invite do |mailer, options|
+    invitation = OpenStruct.new({
+      email: options[:email],
+      owner_name: 'foobar',
+      secret: rand(9000000..1000000).to_s
+    })
+    mailer.invite(invitation).deliver
+end
+```
+
+The mailer and options passed to the `.test` method are yielded to the block.
+
+The `:email` option is the only required option, make sure to add at least this to your test object.
+
+## Helper Methods
+* `.test_friendly_url`(object, route helper as a symbol) - This helper is used for using route helpers, but still staying compatible with using OpenStructs for stubing out the mailing test objects (there is probably a much better way of doing this)

data/lib/mandrill_mailer/mandrill_mailer.rb

@@ -0,0 +1,297 @@
+# MandrilMailer class for sending transactional emails through mandril.
+# Only template based emails are supported at this time.
+
+# Example usage:
+
+# class InvitationMailer < MandrillMailer
+#   default from: 'support@codeschool.com'
+
+#   def invite(invitation)
+#     mandrill_mail template: 'Group Invite',
+#                   subject: I18n.t('invitation_mailer.invite.subject'),
+#                   to: {email: invitation.email, name: 'user level 1'},
+#                   vars: {
+#                     'OWNER_NAME' => invitation.owner_name,
+#                     'INVITATION_URL' => new_invitation_url(email: invitation.email, secret: invitation.secret)
+#                   },
+#                   template_content: {}
+#   end
+# end
+
+# #default:
+#   :from - set the default from email address for the mailer
+
+# .mandrill_mail
+#   :template(required) - Template name from within Mandrill
+
+#   :subject(required) - Subject of the email
+
+#   :to(required) - Accepts an email String, or hash with :name and :email keys
+#     ex. {email: 'someone@email.com', name: 'Bob Bertly'}
+
+#   :vars - A Hash of merge tags made available to the email. Use them in the
+#     email by wrapping them in '*||*' vars: {'OWNER_NAME' => 'Suzy'} is used
+#     by doing: *|OWNER_NAME|* in the email template within Mandrill
+
+#   :template_content - A Hash of values and content for Mandrill editable content blocks.
+#     In MailChimp templates there are editable regions with 'mc:edit' attributes that look
+#     a little like: '<div mc:edit="header">My email content</div>' You can insert content directly into
+#     these fields by passing a Hash {'header' => 'my email content'}
+
+# :headers - Extra headers to add to the message (currently only Reply-To and X-* headers are allowed) {"...": "..."}
+
+# :bcc - Add an email to bcc to
+
+# :tags - Array of Strings to tag the message with. Stats are
+#   accumulated using tags, though we only store the first 100 we see,
+#   so this should not be unique or change frequently. Tags should be
+#   50 characters or less. Any tags starting with an underscore are
+#   reserved for internal use and will cause errors.
+
+# :google_analytics_domains - Array of Strings indicating for which any
+#   matching URLs will automatically have Google Analytics parameters appended
+#   to their query string automatically.
+
+# :google_analytics_campaign - String indicating the value to set for
+#   the utm_campaign tracking parameter. If this isn't provided the email's
+#   from address will be used instead.
+
+
+class MandrillMailer
+  include Rails.application.routes.url_helpers
+  include ActionView::Helpers::NumberHelper
+
+  # Public: Defaults for the mailer. Currently the only option is from:
+  #
+  # options - The Hash options used to refine the selection (default: {}):
+  #             :from - Default from email address
+  #
+  # Examples
+  #
+  #   default from: 'foo@bar.com'
+  #
+  # Returns options
+  def self.default(args)
+    @@defaults ||= {}
+    @@defaults[:from] ||= 'example@email.com'
+    @@defaults.merge!(args)
+  end
+
+  # Public: setup a way to test mailer methods
+  #
+  # mailer_method - Name of the mailer method the test setup is for
+  # block - Block of code to execute to perform the test. The mailer
+  #         and options are passed to the block. The options have to
+  #         contain at least the :email to send the test to.
+  #
+  # Examples
+  #
+  # test_setup_for :invite do |mailer, options|
+  #   invitation = OpenStruct.new({
+  #     email: options[:email],
+  #     owner_name: 'foobar',
+  #     secret: rand(9000000..1000000).to_s
+  #   })
+  #   mailer.invite(invitation).deliver
+  # end
+  #
+  # Returns the duplicated String.
+  def self.test_setup_for(mailer_method, &block)
+    @@mailer_methods ||= {}
+    @@mailer_methods[mailer_method] = block
+  end
+
+  # Public: Executes a test email
+  #
+  # mailer_method - Method to execute
+  # options - The Hash options used to refine the selection (default: {}):
+  #             :email - The email to send the test to.
+  #
+  # Examples
+  #
+  # InvitationMailer.test(:invite, email: 'benny@envylabs.com')
+  #
+  # Returns the duplicated String.
+  def self.test(mailer_method, options={})
+    unless options[:email]
+      raise Exception 'Please specify a :email option(email to send the test to)'
+    end
+
+    if @@mailer_methods[mailer_method]
+      @@mailer_methods[mailer_method].call(self.new, options)
+    else
+      raise Exception "The mailer method: #{mailer_method} does not have test setup"
+    end
+
+  end
+
+  # Public: this enables the api key to be set in an initializer
+  #         ex. MandrillMailer.api_key = ENV[MANDRILL_API_KEY]
+  #
+  # key - Api key for the Mandrill api
+  #
+  #
+  # Returns the key(String)
+  def self.api_key=(key)
+    @@api_key = key
+  end
+
+  # Public: Triggers the stored Mandril params to be sent to the Mandrill api
+  #
+  # text - The String to be duplicated.
+  # count - The Integer number of times to duplicate the text.
+  #
+  # Examples
+  #
+  #   multiplex('Tom', 4)
+  #   # => 'TomTomTomTom'
+  #
+  # Returns the duplicated String.
+  def deliver
+    mandrill = Mailchimp::Mandrill.new(api_key)
+    mandrill.messages_send_template(@data)
+  end
+
+  protected
+
+  # Public: Url helper for creating OpenStruct compatible urls
+  #         This is used for making sure urls will still work with
+  #         OpenStructs used in the email testing code
+  #
+  #         OpenStruct should have a .url property to work with this
+  #
+  # object - Object that would normally be passed into the route helper
+  # route_helper - The route helper as a symbol needed for the url
+  #
+  # Examples
+  #
+  # 'VIDEO_URL' => open_struct_url(video, :code_tv_video_url)
+  #
+  # Returns the url as a string
+  def test_friendly_url(object, route_helper)
+    if object.kind_of? OpenStruct
+      object.url
+    else
+      method(route_helper).call(object)
+    end
+  end
+
+  # Makes this class act as a singleton without it actually being a singleton
+  # This keeps the syntax the same as the orginal mailers so we can swap quickly if something
+  # goes wrong.
+  def self.method_missing(method, *args)
+    return super unless respond_to?(method)
+    new.method(method).call(*args)
+  end
+
+  def self.respond_to?(method, include_private = false)
+    super || instance_methods.include?(method)
+  end
+
+  # Public: Build the hash needed to send to the mandrill api
+  #
+  # args - The Hash options used to refine the selection:
+  #             :template - Template name in Mandrill
+  #             :subject - Subject of the email
+  #             :to - Email to send the mandrill email to
+  #             :vars - Merge vars used in the email for dynamic data
+  #             :bcc - bcc email for the mandrill email
+  #             :tags - Tags for the email
+  #             :google_analytics_domains - Google analytics domains
+  #             :google_analytics_campaign - Google analytics campaign
+  #
+  # Examples
+  #
+  # mandrill_mail template: 'Group Invite',
+  #               subject: I18n.t('invitation_mailer.invite.subject'),
+  #               to: invitation.email,
+  #               vars: {
+  #                 'OWNER_NAME' => invitation.owner_name,
+  #                 'INVITATION_URL' => new_invitation_url(email: invitation.email, secret: invitation.secret)
+  #               }
+  #
+  # Returns the the mandrill mailer class (this is so you can chain #deliver like a normal mailer)
+  def mandrill_mail(args)
+
+    # Mandrill requires template content to be there
+    args[:template_content] = {"blank" => ""} if args[:template_content].blank?
+
+    # format the :to param to what Mandrill expects if a string or array is passed
+    args[:to] = format_to_params(args[:to])
+
+    @data = {"key" => api_key,
+      "template_name" => args[:template],
+      "template_content" => mandrill_args(args[:template_content]),
+      "message" => {
+        "subject" => args[:subject],
+        "from_email" => args[:from] || @@defaults[:from],
+        "from_name" => args[:from_name] || @@defaults[:from],
+        "to" => args[:to],
+        "headers" => args[:headers],
+        "track_opens" => true,
+        "track_clicks" => true,
+        "auto_text" => true,
+        "url_strip_qs" => true,
+        "bcc_address" => args[:bcc],
+        "global_merge_vars" => mandrill_args(args[:vars]),
+        # "merge_vars" =>[
+        #   {
+        #     "rcpt" => "email@email.com"
+        #     "vars" => {"name" => "VARS", "content" => "vars content"}
+        #   }
+        # ]
+
+        "tags" => args[:tags],
+        "google_analytics_domains" => args[:google_analytics_domains],
+        "google_analytics_campaign" => args[:google_analytics_campaign]
+        # "metadata" =>["..."],
+        # "attachments" =>[
+        #   {"type" => "example type", "name" => "example name", "content" => "example content"}
+        # ]
+      }
+    }
+
+    # return self so we can chain deliver after the method call, like a normal mailer.
+    return self
+  end
+
+  def data
+    @data
+  end
+
+  def image_path(image)
+    ActionController::Base.helpers.asset_path(image)
+  end
+
+  def image_url(image)
+    "#{root_url}#{image_path(image).split('/').reject!(&:empty?).join('/')}"
+  end
+
+  # convert a normal hash into the format mandrill needs
+  def mandrill_args(args)
+    args.map do |k,v|
+      {'name' => k, 'content' => v}
+    end
+  end
+
+  # handle if to params is an array of either hashes or strings or the single string
+  def format_to_params(to_params)
+    if to_params.kind_of? Array
+      to_params.map do |p|
+        to_params_item(p)
+      end
+    else
+      [to_params_item(to_params)]
+    end
+  end
+
+  # single to params item
+  def to_params_item(item)
+    return {"email" => item, "name" => "Code School Customer"} unless item.kind_of? Hash
+    item
+  end
+
+  def api_key
+    @@api_key || ''
+  end
+end

data/lib/mandrill_mailer/version.rb

@@ -0,0 +1,3 @@
+module MandrillMailer
+  VERSION = "0.0.1"
+end

data/lib/mandrill_mailer.rb

@@ -0,0 +1,5 @@
+require 'mandrill_mailer/mandrill_mailer'
+
+module MandrillMailer
+
+end

data/mandrill_mailer.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "mandrill_mailer/version"
+
+Gem::Specification.new do |s|
+  s.name        = "mandrill_mailer"
+  s.version     = MandrillMailer::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Adam Rensel"]
+  s.email       = ["adamrensel@codeschool.com"]
+  s.homepage    = ""
+  s.summary     = %q{Transactional Mailer for Mandrill}
+  s.description = %q{Transactional Mailer for Mandrill}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: mandrill_mailer
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Adam Rensel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-24 00:00:00.000000000 Z
+dependencies: []
+description: Transactional Mailer for Mandrill
+email:
+- adamrensel@codeschool.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- lib/mandrill_mailer.rb
+- lib/mandrill_mailer/mandrill_mailer.rb
+- lib/mandrill_mailer/version.rb
+- mandrill_mailer.gemspec
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Transactional Mailer for Mandrill
+test_files: []