mailchimp 0.0.1.alpha

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+coverage.data
+coverage

data/CONTRIBUTORS.markdown

@@ -0,0 +1,15 @@
+* [Chris Kelly](https://github.com/ckdake)
+* [Stafford Brooke](https://github.com/srbiv)
+* [Loren Norman](https://github.com/lorennorman)
+* [Ali Faiz](https://github.com/alif)
+* [Calvin Yu](https://github.com/cyu)
+* [James Kyburz](https://github.com/JamesKyburz)
+* [Justin Ip](https://github.com/ippy04)
+* [elshimone](https://github.com/elshimone)
+* [jlxw](https://github.com/jlxw)
+* [Jon McCartie](https://github.com/jmccartie)
+* [Calvin Yu](https://github.com/cyu)
+* [Dave Worth](https://github.com/daveworth)
+* [Mike Skalnik](https://github.com/skalnik)
+* [Kristopher Murata](https://github.com/krsmurata)
+* [Michael Klishin](https://github.com/michaelklishin)

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,18 @@
+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-api.markdown

@@ -0,0 +1,93 @@
+# Mailchimp::API
+
+API is a simple API wrapper for interacting with [MailChimp API](http://www.mailchimp.com/api) 1.3.
+
+##Requirements
+
+A MailChimp account and API key. You can see your API keys [here](http://admin.mailchimp.com/account/api).
+
+##Usage
+
+There are a few ways to use API:
+
+You can create an instance of the API wrapper:
+
+    api = Mailchimp::API.new("your_api_key")
+
+You can set your api_key globally and call class methods:
+
+    Mailchimp::API.api_key = "your_api_key"
+    Mailchimp::API.lists
+
+You can also set the environment variable 'MC_API_KEY' and API will use it when you create an instance:
+
+    api = Mailchimp::API.new
+
+Fetching data is as simple as calling API methods directly on the wrapper
+object.  The API calls may be made with either camelcase or  underscore
+separated formatting as you see in the "More Advanced Examples" section below.
+
+Check the API [documentation](http://apidocs.mailchimp.com/api/1.3/) for details.
+
+### Fetching Campaigns
+
+For example, to fetch your first 100 campaigns (page 0):
+
+    campaigns = api.campaigns({:start => 0, :limit => 100})
+
+### Fetching Lists
+
+Similarly, to fetch your first 100 lists:
+
+    lists = api.lists({:start => 0, :limit=> 100})
+
+### More Advanced Examples
+
+Getting batch member information for subscribers looks like this:
+
+    info = api.list_member_info({:id => list_id, :email_address => email_array})
+
+or
+
+    info = api.listMemberInfo({:id => list_id, :email_address => email_array})
+
+Fetch open and click detail for recipients of a particular campaign:
+
+    email_stats = api.campaign_email_stats_aim({:cid => campaign_id, :email_address => email_array})
+
+or
+
+    email_stats = api.campaignEmailStatsAIM({:cid => campaign_id, :email_address => email_array})
+
+### Other Stuff
+
+API defaults to a 30 second timeout. You can optionally set your own timeout (in seconds) like so:
+
+    api.timeout = 5
+
+### Export API usage
+
+In addition to the standard API you can make calls to the
+[MailChimp Export API](http://apidocs.mailchimp.com/export/1.0/) using a APIExport object.  Given an existing
+Mailchimp::API object you can request a new Mailchimp::APIExporter object:
+
+    api = Mailchimp::API.new(@api_key)
+    mailchimp_export = api.get_exporter
+
+or you can construct a new object directly:
+
+    mailchimp_export = Mailchimp::APIExport.new(@api_key)
+
+Calling Export API functions is identical to making standard API calls but the
+return value is an Enumerator which loops over the lines returned from the
+Export API.  This is because the data returned from the Export API is a stream
+of JSON objects rather than a single JSON array.
+
+### Error handling
+
+By default you are expected to handle errors returned by the APIs manually.  The
+APIs will return a Hash with two keys "errors", a string containing some textual
+information about the error, and "code", the numeric code of the error.
+
+If you set the `throws_exceptions` boolean attribute for a given instance then
+API will attempt to intercept the errors and raise an exception.

data/README-mandrill.markdown

@@ -0,0 +1,64 @@
+# Mailchimp::Mandrill
+
+Mailchimp::Mandrill is a simple API wrapper for the [Mailchimp Mandrill API](http://mandrillapp.com/api/docs/index.html).
+
+##Requirements
+
+A MailChimp account and a Mandrill specific API key.
+
+Note, to be able to send messages, you'll have to click an e-mail in a message sent to you the first time you try to use that sender.
+
+##Usage
+
+There are a few ways to use Mandrill.
+
+You can create an instance of the API wrapper:
+
+    mandrill = Mailchimp::Mandrill.new("your_api_key")
+
+You can set your api_key globally and call class methods:
+
+    Mailchimp::Mandrill.api_key = "your_api_key"
+    Mailchimp::Mandrill.user_senders(...)
+
+You can also set the environment variable 'MAILCHIMP_MANDRILL_API_KEY' and Mandrill will use it when you create an instance:
+
+    mandrill = Mailchimp::Mandrill.new
+
+### Sending a message
+
+Send a message so a single email:
+
+    response = mandrill.messages_send({
+        :message      => { 
+            :subject => 'your subject', 
+            :html => '<html>hello world</html>', 
+            :text => 'hello world', 
+            :from_name => 'John Smith', 
+            :from_email => 'support@somedomain.com', 
+            :to => ['user@someotherdomain.com']
+        }
+    })
+
+Calling other methods is as simple as calling API methods directly on the Mandrill instance (e.g. mandrill.users_verify_sender(...)). Check the API [documentation](http://mandrillapp.com/api/docs/index.html)) for more information about API calls and their parameters.
+
+
+### Plugging into ActionMailer
+
+You can tell ActionMailer to send mail using Mandrill by adding the follow to to your config/application.rb or to the proper environment (eg. config/production.rb) :
+    
+    config.action_mailer.delivery_method = :mailchimp_mandrill
+    config.action_mailer.mailchimp_mandrill_settings = {
+          :api_key => "your_mailchimp_mandrill_apikey",
+          :track_clicks => true,
+          :track_opens  => true, 
+          :from_name    => "Change Me"
+     }
+
+These setting will allow you to use ActionMailer as you normally would, any calls to mail() will be sent using Mandrill
+
+### Other Stuff
+
+Mandrill defaults to a 30 second timeout. You can optionally set your own timeout (in seconds) like so:
+
+    sts.timeout = 5

data/README-sts.markdown

@@ -0,0 +1,70 @@
+# Mailchimp::STS
+
+STS is a simple API wrapper for the [MailChimp STS API](http://http://apidocs.mailchimp.com/sts/1.0/) 1.0, which wraps Amazon SES.
+    
+##Requirements
+
+A paid MailChimp account, MailChimp API key, and Amazon AWS account with SES ready to go. You can see your API keys [here](http://admin.mailchimp.com/account/api). Caveats include the inability to send to unconfirmed email addresses until you request (and Amazon provides) production access to your AWS account.
+
+##Usage
+
+There are a few ways to use STS.
+
+You can create an instance of the API wrapper:
+
+    sts = Mailchimp::STS.new("your_api_key")
+
+You can set your api_key globally and call class methods:
+
+    Mailchimp::STS.api_key = "your_api_key"
+    Mailchimp::STS.send_email(...)
+
+You can also set the environment variable 'MAILCHIMP_API_KEY' and STS will use it when you create an instance:
+
+    sts = Mailchimp::STS.new
+
+### Sending a message
+
+Send a message so a single email:
+
+    response = sts.send_email({
+        :track_opens  => true, 
+        :track_clicks => true, 
+        :tags         => ["awesome", "tags", "here"] #optional STS tags
+        :message      => { 
+            :subject => 'your subject', 
+            :html => '<html>hello world</html>', 
+            :text => 'hello world', 
+            :from_name => 'John Smith', 
+            :from_email => 'support@somedomain.com', 
+            :to_email => ['user@someotherdomain.com']
+        }
+    })
+
+Calling other methods is as simple as calling API methods directly on the STS instance (e.g. u.get_send_quota, u.verify_email_address, and so on). Check the API [documentation](http://apidocs.mailchimp.com/sts/1.0/) for more information about API calls and their parameters.
+
+
+### Plugging into ActionMailer
+
+You can tell ActionMailer to send mail using Mailchimp STS by adding the follow to to your config/application.rb or to the proper environment (eg. config/production.rb) :
+    
+    config.action_mailer.delivery_method = :mailchimp_sts
+    config.action_mailer.mailchimp_sts_settings = {
+          :api_key => "your_mailchimp_apikey",
+          :track_clicks => true,
+          :track_opens  => true, 
+          :from_name    => "Change Me"
+          :tags         => ["awesome", "tags", "here"] #optional STS tags
+     }
+
+These setting will allow you to use ActionMailer as you normally would, any calls to mail() will be sent using Mailchimp STS
+
+If, for some reason, you want to use ActionMailer and change your tags dynamically at runtime, you can do something like:
+
+    ActionMailer::Base.mailchimp_sts_settings[:tags] = ["dynamically", "set", "tags"]
+
+### Other Stuff
+
+STS defaults to a 30 second timeout. You can optionally set your own timeout (in seconds) like so:
+
+    sts.timeout = 5

data/README.markdown

@@ -0,0 +1,58 @@
+# mailchimp
+
+Mailchimp is a simple API wrapper public Mailchimp APIs.
+
+This is heavily based on https://github.com/amro/uakari/ and https://github.com/amro/gibbon/, and adds
+support for the private beta release of Mandrill.
+
+While this works for some simple use cases, it comes with warranty of any kind and may not work for 
+your needs yet!
+
+We welcome bug reports and pull requests, and will remove the .alpha label from this gem once we are
+confident that it should work out of the box for most usage scenarios.
+
+##Installation
+
+        # This supercedes uakari and gibbon
+        $ gem install mailchimp
+
+##Requirements
+
+A MailChimp account, MailChimp API key, and any extra setup/keys for other services/APIs that
+you want to use.
+
+##Basic Usage
+
+See README-api.markdown for details about the API class, which supersedes the Gibbon Gem
+
+        api      = Mailchimp::API.new("your_api_key")
+
+See README-sts.markdown for details about the STS class, which supersedes the Uakari Gem
+
+        sts      = Mailchimp::STS.new("your_api_key")
+        
+See README-mandrill for details about the Mandrill class
+
+        mandrill = Mailchimp::Mandrill.new("your_api_key")
+        
+##Examples
+
+Take a look in the examples/ folder for examples using each of the APIs. The only actions these perform
+are either read only or only send emails to you or the address you specify, so it's ok to use your real
+Mailchimp API keys for them. run them like:
+
+        ruby examples/api_example.rb
+        ruby examples/sts_example.rb
+        ruby examples/mandrill_example.rb
+
+##Development
+
+Write tests before you change anything, run tests before you commit anything:
+
+        $ rake test
+
+We welcome concise pull requests that match the style of this gem and have appropriate tests.
+
+##Contributors
+
+See CONTRIBUTORS.markdown for the people that have contributed in some way to this Gem

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task default: [:test]
+
+namespace :cover_me do
+  desc "Generates and opens code coverage report."
+  task :report do
+    require 'cover_me'
+    CoverMe.complete!
+  end
+end
+
+task :test do
+  Rake::Task['cover_me:report'].invoke
+end
+
+task :spec do
+  Rake::Task['cover_me:report'].invoke
+end

data/examples/api_example.rb

@@ -0,0 +1,17 @@
+if ENV['MAILCHIMP_API_KEY'] == nil
+  puts 'Set ENV["MAILCHIMP_API_KEY"] to use this example'
+  exit
+end
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'mailchimp' # Use the 'mailchimp' gem instead
+
+# Set MAILCHIMP_API_KEY in your environment to use this.
+api = Mailchimp::API.new(ENV['MAILCHIMP_API_KEY'])
+
+puts "Your lists:"
+
+api.lists['data'].each do |list|
+  puts "\t #{list['name']}"
+end

data/examples/mandrill_example.rb

@@ -0,0 +1,35 @@
+if ENV['MAILCHIMP_MANDRILL_API_KEY'] == nil
+  puts 'Set ENV["MAILCHIMP_MANDRILL_API_KEY"] to use this example'
+  exit
+end
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'mailchimp' # Use the 'mailchimp' gem instead
+
+# Set MAILCHIMP_MANDRILL_API_KEY in your environment to use this.
+mandrill = Mailchimp::Mandrill.new(ENV['MAILCHIMP_MANDRILL_API_KEY'])
+
+puts "Your username is #{mandrill.users_info['username']}. lets email that person as that person to that person!"
+
+response = mandrill.messages_send(
+  message: {
+    html: "<html><body><h1>Test</h1></body></html>",
+    text: "Test",
+    subject: "Test Message From Mandrill",
+    from_email: mandrill.users_info['username'],
+    from_name: 'Mandrill User',
+    to: [mandrill.users_info['username']]
+  }
+)
+
+puts "valid senders:"
+
+mandrill.users_senders.map { |sender| puts "\t#{sender['address']}" }
+
+puts "sending a validation request for your user..."
+
+mandrill.users_verify_sender(email: mandrill.users_info['username'])
+
+puts "Sent! Status: #{response['status']}"
+

data/examples/sts_example.rb

@@ -0,0 +1,25 @@
+if ENV['MAILCHIMP_API_KEY'] == nil
+  puts 'Set ENV["MAILCHIMP_API_KEY"] to use this example'
+  exit
+end
+
+if ENV['TEST_EMAIL_ADDRESS'] == nil
+  puts 'Set ENV["TEST_EMAIL_ADDRESS"] to use this example'
+  exit
+end
+
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'mailchimp' # Use the 'mailchimp' gem instead
+
+# Set MAILCHIMP_API_KEY in your environment to use this. set TEST_EMAIL_ADDRESS to use this.
+sts = Mailchimp::STS.new(ENV['MAILCHIMP_API_KEY'])
+
+puts "valid senders:"
+
+puts sts.list_verified_email_addresses['email_addresses'].map { |address| puts "\t#{address}" }
+
+puts "sending a validation request for your user..."
+
+sts.verify_email_address(email: ENV['TEST_EMAIL_ADDRESS'])

data/lib/mailchimp/API.rb

@@ -0,0 +1,94 @@
+module Mailchimp
+  class API
+    include HTTParty
+    format :plain
+    default_timeout 30
+
+    attr_accessor :api_key, :timeout, :throws_exceptions
+
+    def initialize(api_key = nil, extra_params = {})
+      @api_key = api_key || ENV['MAILCHIMP_API_KEY'] || self.class.api_key
+      @default_params = {:apikey => @api_key}.merge(extra_params)
+      @throws_exceptions = false
+    end
+
+    def api_key=(value)
+      @api_key = value
+      @default_params = @default_params.merge({:apikey => @api_key})
+    end
+
+    def get_exporter
+      APIExport.new(@api_key, @default_params)
+    end
+
+    def base_api_url
+      "https://#{dc_from_api_key}api.mailchimp.com/1.3/?method="
+    end
+
+    protected
+
+    def call(method, params = {})
+      api_url = base_api_url + method
+      params = @default_params.merge(params)
+      response = self.class.post(api_url, :body => CGI::escape(params.to_json), :timeout => @timeout)
+
+      begin
+        response = JSON.parse(response.body)
+      rescue
+        response = JSON.parse('['+response.body+']').first
+      end
+
+      if @throws_exceptions && response.is_a?(Hash) && response["error"]
+        raise "Error from MailChimp API: #{response["error"]} (code #{response["code"]})"
+      end
+
+      response
+    end
+
+    def method_missing(method, *args)
+      method = method.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase } #Thanks for the gsub, Rails
+      method = method[0].chr.downcase + method[1..-1].gsub(/aim$/i, 'AIM')
+      args = {} unless args.length > 0
+      args = args[0] if args.is_a?(Array)
+      call(method, args)
+    end
+
+    class << self
+      attr_accessor :api_key
+
+      def method_missing(sym, *args, &block)
+        new(self.api_key).send(sym, *args, &block)
+      end
+    end
+
+    def dc_from_api_key
+      (@api_key.nil? || @api_key.length == 0 || @api_key !~ /-/) ? '' : "#{@api_key.split("-").last}."
+    end
+  end
+
+  class APIExport < API
+    def initialize(api_key = nil, extra_params = {})
+      super(api_key, extra_params)
+    end
+
+    protected
+
+    def export_api_url
+      "http://#{dc_from_api_key}api.mailchimp.com/export/1.0/"
+    end
+
+    def call(method, params = {})
+      api_url = export_api_url + method + "/"
+      params = @default_params.merge(params)
+      response = self.class.post(api_url, :body => params, :timeout => @timeout)
+
+      lines = response.body.lines
+      if @throws_exceptions
+        first_line_object = JSON.parse(lines.first) if lines.first
+        raise "Error from MailChimp Export API: #{first_line_object["error"]} (code #{first_line_object["code"]})" if first_line_object.is_a?(Hash) && first_line_object["error"]
+      end
+
+      lines
+    end
+  end
+end

data/lib/mailchimp/ext/httparty.rb

@@ -0,0 +1,34 @@
+module HTTParty
+  module HashConversions
+    # @param key<Object> The key for the param.
+    # @param value<Object> The value for the param.
+    #
+    # @return <String> This key value pair as a param
+    #
+    # @example normalize_param(:name, "Bob Jones") #=> "name=Bob%20Jones&"
+    def self.normalize_param(key, value)
+      param = ''
+      stack = []
+
+      if value.is_a?(Array)
+        param << Hash[*(0...value.length).to_a.zip(value).flatten].map {|i,element| normalize_param("#{key}[#{i}]", element)}.join
+      elsif value.is_a?(Hash)
+        stack << [key,value]
+      else
+        param << "#{key}=#{URI.encode(value.to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))}&"
+      end
+
+      stack.each do |parent, hash|
+        hash.each do |key, value|
+          if value.is_a?(Hash)
+            stack << ["#{parent}[#{key}]", value]
+          else
+            param << normalize_param("#{parent}[#{key}]", value)
+          end
+        end
+      end
+
+      param
+    end
+  end
+end

data/lib/mailchimp/handlers/mandrill_delivery_handler.rb

@@ -0,0 +1,47 @@
+require 'action_mailer'
+
+module Mailchimp
+  class MandrillDeliveryHandler
+    attr_accessor :settings
+
+    def initialize options
+      self.settings = {:track_opens => true, :track_clicks => true}.merge(options)
+    end
+
+    def deliver! message
+      message_payload = {
+        :track_opens => settings[:track_opens],
+        :track_clicks => settings[:track_clicks],
+        :message => {
+          :subject => message.subject,
+          :from_name => settings[:from_name],
+          :from_email => message.from.first,
+          :to_email => message.to
+        }
+      }
+
+      mime_types = {
+        :html => "text/html",
+        :text => "text/plain"
+      }
+
+      get_content_for = lambda do |format|
+        content = message.send(:"#{format}_part")
+        content ||= message if message.content_type =~ %r{#{mime_types[format]}}
+        content
+      end
+
+      [:html, :text].each do |format|
+        content = get_content_for.call(format)
+        message_payload[:message][format] = content.body if content
+      end
+
+      message_payload[:tags] = settings[:tags] if settings[:tags]
+
+      Mandrill.new(settings[:api_key]).send_email(message_payload)
+    end
+
+  end
+end
+
+ActionMailer::Base.add_delivery_method :mailchimp_mandrill, Mailchimp::MandrillDeliveryHandler

data/lib/mailchimp/handlers/sts_delivery_handler.rb

@@ -0,0 +1,47 @@
+require 'action_mailer'
+
+module Mailchimp
+  class StsDeliveryHandler
+    attr_accessor :settings
+
+    def initialize options
+      self.settings = {:track_opens => true, :track_clicks => true}.merge(options)
+    end
+
+    def deliver! message
+      message_payload = {
+        :track_opens => settings[:track_opens],
+        :track_clicks => settings[:track_clicks],
+        :message => {
+          :subject => message.subject,
+          :from_name => settings[:from_name],
+          :from_email => message.from.first,
+          :to_email => message.to
+        }
+      }
+
+      mime_types = {
+        :html => "text/html",
+        :text => "text/plain"
+      }
+
+      get_content_for = lambda do |format|
+        content = message.send(:"#{format}_part")
+        content ||= message if message.content_type =~ %r{#{mime_types[format]}}
+        content
+      end
+
+      [:html, :text].each do |format|
+        content = get_content_for.call(format)
+        message_payload[:message][format] = content.body if content
+      end
+
+      message_payload[:tags] = settings[:tags] if settings[:tags]
+
+      STS.new(settings[:api_key]).send_email(message_payload)
+    end
+
+  end
+end
+
+ActionMailer::Base.add_delivery_method :mailchimp_sts, Mailchimp::StsDeliveryHandler