monkeywrench 0.1.5

data/README.mdown

@@ -0,0 +1,78 @@
+# MonkeyWrench
+MonkeyWrench is a rubyesque API for interfacing with [Mailchimp](http://www.mailchimp.com) (or show me some love by registering [via my affiliate link](http://eepurl.com/Ge71)). It makes managing a mailing list, adding/removing subscribers, and setting up autoresponders so easy that even a monkey could do it.
+
+The API provided by MonkeyWrench takes an idiomatic ruby approach where possible, so supported parameters and options may differ slightly to what is documented in the official Mailchimp API documentation. Where possible, refer to the MonkeyWrench docs.
+
+## Getting Started
+
+### Installation
+
+The easiest way to get started is to install the gem:
+
+    gem install monkeywrench
+    
+### Usage
+
+To get started, you need to first connect to the appropriate datacenter with your API key:
+
+    MonkeyWrench::Config.new(:datacenter => "us1", 
+                             :apikey => "your-api-key-goes-here")
+
+From there you've got a rich API for managing Lists and Members. To subscribe a new user to a list simply do the following:
+
+    list = MonkeyWrench::List.find_by_name("My Example List")
+    list.subscribe("foo@bar.com")
+    
+## Further Reading
+
+For more information, [check the documentation](http://rdoc.info/projects/rubypond/monkeywrench)
+
+## Compatibility
+
+Tested on the following versions:
+
+* 1.8.7
+* 1.9.2
+* Ruby Enterprise Edition 1.8.7
+* Rubinius 1.1.1
+* JRuby 1.5.5
+
+It may work in 1.8.6 too, but a test dependency (WebMock) won't work so tests aren't currently automated against that version.
+
+## Status
+
+The library is currently under development, but in production use for many clients. It's still currently using the 1.2 version of the Mailchimp API (Mailchimp haven't made any deprecation announcements yet, and they still support 1.1 so it shouldn't be an issue any time soon). I'm working towards a switch to 1.3.
+
+## Contributing
+
+Patches and pull requests are gladly accepted. Please make sure that you include associated tests and documentation and that your commit messages are brief but descriptive.
+
+## Credits & Contributions
+
+* [David Heath](https://davidheath.org/)
+* [Maxime Guilbot](https://github.com/maxime)
+* [Keith Marcum](https://github.com/kamarcum)
+
+## License
+
+MonkeyWrench is released under the MIT license.
+
+Copyright (c) 2010 Glenn Gillen
+
+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/Rakefile

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'rake'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+spec_data = File.open('monkeywrench.gemspec').read
+spec = nil
+Thread.new do
+  spec = eval("#{spec_data}")
+end.join
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = false
+end

data/lib/monkey_wrench.rb

@@ -0,0 +1 @@
+require "#{File.dirname(__FILE__)}/monkeywrench"

data/lib/monkeywrench.rb

@@ -0,0 +1,10 @@
+require "httparty"
+base_dir = File.join(File.dirname(__FILE__), "monkeywrench")
+["base", "config", "hash", "list", "error", "member"].each do |lib|
+  require File.join(base_dir, lib)
+end
+
+begin
+  OpenStruct.class_eval { undef :id, :type }
+rescue NameError
+end

data/lib/monkeywrench/array.rb

@@ -0,0 +1,9 @@
+require 'cgi'
+module MonkeyWrench
+  module Array
+  end
+end
+
+class Array
+  include MonkeyWrench::Array
+end

data/lib/monkeywrench/base.rb

@@ -0,0 +1,97 @@
+require 'ostruct'
+module MonkeyWrench
+  class Base < OpenStruct
+    include HTTParty
+
+    @@apikey = nil
+    @@datacenter = nil
+    @@dryrun = false
+
+    class << self
+      def default_query_params
+        { :output => "json", :apikey=> @@apikey}
+      end
+
+      def base_uri
+        "http://#{datacenter}.api.mailchimp.com/1.2/"
+      end
+
+      def default_retry_limit
+        3
+      end
+
+      def get(params, http_options = {})
+        if @@dryrun
+          puts "GET #{base_uri} #{params.merge(default_query_params).inspect}"
+          return {}
+        else
+          robustly(http_options) do
+            response = super(base_uri, http_options.merge(:query => params.merge(default_query_params)))
+            handle_errors(response.parsed_response)
+          end
+        end
+      end
+
+      def post(params, http_options = {})
+        if @@dryrun
+          puts "POST #{base_uri} #{params.merge(default_query_params).inspect}"
+          return {}
+        else
+          robustly(http_options) do
+            post_params = params.dup
+            get_params = default_query_params.merge(:method => post_params.delete(:method))
+            response = super(base_uri, http_options.merge(:body => post_params, :query => get_params))
+            handle_errors(response.parsed_response)
+          end
+        end
+      end
+
+      def handle_errors(objects)
+        return objects unless objects.respond_to?(:has_key?)
+
+        if objects.has_key?("error")
+          objects.replace({ "error" => MonkeyWrench::Error.new(objects['error'], objects['code']) })
+        elsif objects.has_key?("errors")
+          objects["errors"] = objects["errors"].map do |err|
+            message = err.delete('message')
+            code = err.delete('code')
+            MonkeyWrench::Error.new(message, code, err)
+          end
+        end
+        objects
+      end
+
+      def apikey
+        @@apikey
+      end
+
+      def datacenter
+        @@datacenter
+      end
+    end
+
+    private
+      def self.robustly(http_options, &block)
+        retry_limit = http_options[:retry_limit] || default_retry_limit
+        attempts = 0
+        while attempts < retry_limit
+          begin
+            attempts += 1
+            return yield
+          rescue Timeout::Error => e
+            if attempts == retry_limit
+              raise e
+            end
+          end
+        end
+      end
+
+      def get(*args)
+        self.class.get(*args)
+      end
+
+      def post(*args)
+        self.class.post(*args)
+      end
+  end
+end

data/lib/monkeywrench/config.rb

@@ -0,0 +1,35 @@
+require 'yaml'
+module MonkeyWrench
+  class Config < MonkeyWrench::Base
+    # Establishes a connection to the Mailchimp API.
+    #
+    # Can be called with either a path to a file containing credentials, or 
+    # a hash of credentials. The formats of each are:
+    #
+    # File:
+    #   mailchimp:
+    #     datacenter: us1 # Or whatever DC you use
+    #     apikey: your-api-key-goes-here
+    # Hash:
+    #   { :datacenter => "us1", :apikey => "your-api-key-goes-here"}
+    #
+    # @example
+    #     MonkeyWrench::Config.new(:datacenter => "us1", 
+    #                              :apikey => "your-api-key-goes-here")
+    #
+    # @param [String, Hash] credentials accepts either a String pointing to a file
+    # containing the credentials, or a hash of credentials. 
+    def initialize(credentials)
+      if credentials.is_a?(String)
+        config = YAML.load_file(credentials)["mailchimp"]
+        config.collect_kv!{|k,v| [k.to_sym, v]}
+      else
+        config = credentials
+      end
+      @@apikey = config[:apikey]
+      @@datacenter = config[:datacenter]
+      @@dryrun = config[:dryrun] || false
+      super({})
+    end
+  end
+end

data/lib/monkeywrench/error.rb

@@ -0,0 +1,104 @@
+module MonkeyWrench
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message, code, extra_fields = {}) 
+      super(message)
+      @code = code
+      @extra_fields = extra_fields
+    end
+
+    def type
+      types[@code]
+    end
+
+    def method_missing(sym, *args, &block)
+      return @extra_fields[sym.to_s] if @extra_fields.has_key?(sym.to_s)
+    end
+    
+    def types
+      {
+        -32601 => 'ServerError_MethodUnknown',
+        -32602 => 'ServerError_InvalidParameters',
+        -99 => 'Unknown_Exception',
+        -98 => 'Request_TimedOut',
+        -92 => 'Zend_Uri_Exception',
+        -91 => 'PDOException',
+        -91 => 'Avesta_Db_Exception',
+        -90 => 'XML_RPC2_Exception',
+        -90 => 'XML_RPC2_FaultException',
+        -50 => 'Too_Many_Connections',
+        0 => 'Parse_Exception',
+        100 => 'User_Unknown',
+        101 => 'User_Disabled',
+        102 => 'User_DoesNotExist',
+        103 => 'User_NotApproved',
+        104 => 'Invalid_ApiKey',
+        105 => 'User_UnderMaintenance',
+        120 => 'User_InvalidAction',
+        121 => 'User_MissingEmail',
+        122 => 'User_CannotSendCampaign',
+        123 => 'User_MissingModuleOutbox',
+        124 => 'User_ModuleAlreadyPurchased',
+        125 => 'User_ModuleNotPurchased',
+        126 => 'User_NotEnoughCredit',
+        127 => 'MC_InvalidPayment',
+        200 => 'List_DoesNotExist',
+        210 => 'List_InvalidInterestFieldType',
+        211 => 'List_InvalidOption',
+        212 => 'List_InvalidUnsubMember',
+        213 => 'List_InvalidBounceMember',
+        214 => 'List_AlreadySubscribed',
+        215 => 'List_NotSubscribed',
+        220 => 'List_InvalidImport',
+        221 => 'MC_PastedList_Duplicate',
+        222 => 'MC_PastedList_InvalidImport',
+        230 => 'Email_AlreadySubscribed',
+        231 => 'Email_AlreadyUnsubscribed',
+        232 => 'Email_NotExists',
+        233 => 'Email_NotSubscribed',
+        250 => 'List_MergeFieldRequired',
+        251 => 'List_CannotRemoveEmailMerge',
+        252 => 'List_Merge_InvalidMergeID',
+        253 => 'List_TooManyMergeFields',
+        254 => 'List_InvalidMergeField',
+        270 => 'List_InvalidInterestGroup',
+        271 => 'List_TooManyInterestGroups',
+        300 => 'Campaign_DoesNotExist',
+        301 => 'Campaign_StatsNotAvailable',
+        310 => 'Campaign_InvalidAbsplit',
+        311 => 'Campaign_InvalidContent',
+        312 => 'Campaign_InvalidOption',
+        313 => 'Campaign_InvalidStatus',
+        314 => 'Campaign_NotSaved',
+        315 => 'Campaign_InvalidSegment',
+        316 => 'Campaign_InvalidRss',
+        317 => 'Campaign_InvalidAuto',
+        318 => 'MC_ContentImport_InvalidArchive',
+        330 => 'Invalid_EcommOrder',
+        350 => 'Absplit_UnknownError',
+        351 => 'Absplit_UnknownSplitTest',
+        352 => 'Absplit_UnknownTestType',
+        353 => 'Absplit_UnknownWaitUnit',
+        354 => 'Absplit_UnknownWinnerType',
+        355 => 'Absplit_WinnerNotSelected',
+        500 => 'Invalid_Analytics',
+        501 => 'Invalid_DateTime',
+        502 => 'Invalid_Email',
+        503 => 'Invalid_SendType',
+        504 => 'Invalid_Template',
+        505 => 'Invalid_TrackingOptions',
+        506 => 'Invalid_Options',
+        507 => 'Invalid_Folder',
+        508 => 'Invalid_URL',
+        550 => 'Module_Unknown',
+        551 => 'MonthlyPlan_Unknown',
+        552 => 'Order_TypeUnknown',
+        553 => 'Invalid_PagingLimit',
+        554 => 'Invalid_PagingStart'
+      }
+    end
+  end
+end
+
+ 

data/lib/monkeywrench/hash.rb

@@ -0,0 +1,69 @@
+require 'cgi'
+module MonkeyWrench
+  module Hash
+ 
+    # Takes a block that returns a [key, value] pair
+    # and builds a new hash based on those pairs
+    # Courtesy of http://snuxoll.com/post/2009/02/13/ruby-better-hashcollect
+    def collect_kv
+      result = {}
+      each do |k,v|
+        new_k, new_v = yield k, v
+        result[new_k] = new_v
+      end
+      result
+    end
+    
+    def collect_kv!(&blk)
+      replace(self.collect_kv(&blk))
+    end
+    
+    def escape_keys!
+      collect_kv!{|k,v| [CGI.escape(k.to_s), v]}
+    end
+
+    def to_mailchimp(index = nil, parent_name = nil)
+      result = self.collect_kv do |k,v|
+        if v.is_a?(Array) && v.first.is_a?(Hash)
+          i = 0
+          v = v.inject({}) do |acc,hash|
+            acc.merge!(hash.to_mailchimp(i, k))
+            i += 1
+            acc
+          end
+        elsif v.is_a?(Hash)
+          if parent_name
+            v = v.collect_kv do |key,val| 
+              keyname = CGI.escape("#{parent_name.to_s}[#{key.to_s.upcase}]")
+              [keyname, val.to_s]
+            end
+          else
+            v = { k => v }.to_mailchimp(nil, k)
+          end
+        elsif v.is_a?(Array)
+          results = {}
+          i = 0
+          v.each do |val|
+            keyname = CGI.escape("#{k}[#{i}]")
+            results[keyname] = val.to_s
+            i += 1
+          end
+          v = results
+        end
+        k = k.to_s
+        k = "[#{index}][#{k.upcase}]" if index
+        k = [parent_name, k].join if k != parent_name.to_s
+        [CGI.escape(k), v]
+      end
+      if result.detect{|k,v| v.is_a?(Hash)}
+        result.values.first
+      else
+        result
+      end
+    end
+  end
+end
+
+class Hash
+  include MonkeyWrench::Hash
+end

data/lib/monkeywrench/list.rb

@@ -0,0 +1,353 @@
+require 'cgi'
+
+module MonkeyWrench
+  class List < MonkeyWrench::Base
+    # Finds a given list by name
+    #
+    # @example
+    #   MonkeyWrench::List.find_by_name("My Example List")
+    #
+    # @param [String] list_name the list name
+    # @return [MonkeyWrench::List] the first list found with a matching name
+    def self.find_by_name(list_name)
+      lists = find_all.detect{|list| list.name == list_name}
+    end
+
+    # Will compare another list against the current one and return true if 
+    # they are the same (based on list ID)
+    #
+    # @example
+    #   list1 = MonkeyWrench::List.find("0a649eafc3")
+    #   list2 = MonkeyWrench::List.find("9f9d54a0c4")
+    #   list3 = MonkeyWrench::List.find("0a649eafc3") # Same as list1!!
+    #   list1 == list2 # false
+    #   list1 == list3 # true
+    # @param [MonkeyWrench::List] other_list Other list to compare against
+    # @return [Boolean]
+    def ==(other_list)
+      other_list.is_a?(self.class) && self.id == other_list.id
+    end
+
+    # Finds a given list by ID
+    #
+    # @example
+    #   MonkeyWrench::List.find("0a649eafc3")
+    #
+    # @param [String] id the unique Mailchimp list ID
+    # @return [MonkeyWrench::List] the list
+    def self.find(id)
+      find_all.find{|e| e.id == id}
+    end
+
+    # Finds all lists
+    #
+    # @example
+    #   MonkeyWrench::List.find_all
+    #
+    # @return [Array<MonkeyWrench::List>]
+    def self.find_all
+      @@lists ||= post({ :method => "lists" }).map do |list|
+        List.new(list)
+      end
+    end
+    
+    class << self
+      alias :all :find_all
+    end
+
+    # Clears the List cache (results from List.find_all are cached for
+    # performance reasons)
+    #
+    # @example
+    #   MonkeyWrench::List.clear!
+    #
+    # @return nil
+    def self.clear!
+      @@lists = nil
+    end
+
+    # Returns all members for this list
+    #
+    # @example Find all members that have unsubscribed in the last 24 hours:
+    #   MonkeyWrench.members(:status => "unsubscribed",
+    #                        :since => Time.now - 86400)
+    #
+    # @param [Hash] options additional option to include when searching.
+    # @option options [String] :status ('subscribed') Filter the list members by status. Can be one of the following: "subscribed", "unsubscribed", "cleaned", "updated".
+    # @option options [DateTime] :since Return all members whose status has changed or whose profile has changed since this date/time (in GMT).
+    # @option options [Integer] :start (0) For large datasets, the page number to start at.
+    # @option options [Integer] :limit (100) For large datasets, the number of results to return. Upper limit is set at 15000.
+    # @option options [Boolean] :full_details (true) Return full member details and not just email address and timestamp.
+    # @return [Array<MonkeyWrench::Member>] 
+    def members(options = {})
+      if options[:since]
+        options[:since] = options[:since].strftime("%Y-%m-%d %H:%M:%S")
+      end
+      options.merge!(:id => self.id, :method => "listMembers")
+      response = post(options)
+      if options[:full_details]
+        response.map do |response_user|
+          member(response_user["email"])
+        end
+      else
+        response.map do |response_user|
+          MonkeyWrench::Member.new(response_user)
+        end
+      end
+    end
+
+    # Enumerates over each member and executes the provided block. Will 
+    # automatically page and batch requests for members.
+    #
+    # @example
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   emails = []
+    #   list.each_member do |member|
+    #     emails << member.email
+    #   end
+    #
+    # @param [Proc] &block code to execute for each member
+    def each_member(&block)
+      page = 0
+      loop do
+        batch = members(:start => page, :limit => 15000)
+        break if batch.empty?
+        batch.each do |member|
+          yield member
+        end
+        page += 1
+      end
+    end
+
+    # Updates details of list members
+    #
+    # @example Update a single member's email address
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   member = {:email => "foo@bar.com", :new_email => "bar@foo.com"}
+    #   list.update_members(member)
+    #
+    # @example Update multiple members' email addresses
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   members = [{:email => "foo@bar.com", :new_email => "bar@foo.com"},
+    #              {:email => "bob@bar.com", :new_email => "bob@foo.com"}]
+    #   list.update_members(members)
+    #
+    # @param [Hash, Array<Hash>] members details of member(s) to update details 
+    #   of. Members are matched based on the value of :email, to update the 
+    #   email address assign the new address to :new_email. All other field 
+    #   names are lowercase symbols representing the MERGEVAR name in 
+    #   Mailchimp (e.g., FNAME is :fname)
+    # @param [Hash] options additional options when updating members.
+    # @option options [String] :email_type Change the email type preference for the member ('html', 'text', or 'mobile').
+    # @option options [Boolean] :replace_interests (true) replace the interest groups provided (will append interest groups to existing values when false).
+    def update_members(members, options = {})
+      members = members.is_a?(Array) ? members : [members]
+      options.merge!(:id => self.id, :method => "listUpdateMember")
+      members.each do |member|
+        mailchimp_args = {:email_address => member[:email]}
+        member[:email] = member[:new_email]
+        member.delete(:new_email)
+        mailchimp_args.merge!({ :merge_vars => member }.to_mailchimp)
+        post(options.merge(mailchimp_args))
+      end
+    end
+
+    # Find a member in this list with the given email address
+    #
+    # @example
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   list.member("glenn@rubypond.com")
+    #
+    # @param [String] email members email address
+    # @return [MonkeyWrench::Member]
+    def member(email)
+      response = post(:id => self.id, :method => "listMemberInfo", :email_address => email)
+      if response['error']
+        raise response['error']
+      else
+        MonkeyWrench::Member.new(response)
+      end
+    end
+
+    # Check if an email has subscribed to the list
+    #
+    # @example
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   list.member?("glenn@rubypond.com")
+    #
+    # @param [String] email members email address
+    # @return [Boolean]
+    def member?(email)
+      response = post(:id => self.id, :method => "listMemberInfo", :email_address => email)
+      if response['error']
+        false
+      else
+        true
+      end
+    end
+
+    # Subscribes a new member to the list
+    #
+    # @example Subscribe a new email address
+    #   list.subscribe("foo@bar.com")
+    #
+    # @example Subscribe a new member with extended details
+    #   list.subscribe({:email => "foo@bar.com", :type => :html})
+    #
+    # @example Subscribe multiple new members
+    #   subscribers = [{:email => "foo@bar.com", :type => :html},
+    #                  {:email => "bar@foo.com", :type => :html}]
+    #   list.subscribe(subscribe, :send_welcome => true, :double_optin => false)
+    #
+    # @param [String, Hash, Array<Hash>] contact_details the email address or hash of values for the new member
+    # @param [Hash] opts options when adding new member
+    # @option opts [Boolean] :send_welcome (false) if :double_optin if false and this is 
+    #   true, send the lists 'Welcome Email' to the member(s). Will not send email if 
+    #  updating an existing member.
+    # @option opts [Boolean] :double_optin (true) send an opt-in confirmation email
+    # @option opts [Boolean] :update_existing (false) update members that are already subscribed to the list or to return an error (false returns error)
+    # @option opts [Boolean] :replace_interests (true) replace interest groups or append to existing interest groups (false appends to groups)
+    def subscribe(contact_details, opts = {})
+      if contact_details.is_a?(Array)
+        return subscribe_many(contact_details, opts)
+      else
+        if contact_details.is_a?(Hash)
+          email_address = contact_details.delete(:email)
+          opts = opts.merge(contact_details)
+        else
+          email_address = contact_details
+        end
+        subscribe_one(email_address, opts)
+        return { :success => 1, :errors => []}
+      end
+    end
+
+    # Unsubscribes a person (or list of people) from the list
+    #
+    # @example Unsubscribe a single user
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   list.unsubscribe("glenn@rubypond.com", :send_goodbye => true) # Unsubscribe a single person
+    #
+    # @example Unsubscribe a list of users
+    #   emails = ["glenn@rubypond.com", "me@glenngillen.com"]
+    #   list.unsubscribe(emails, :send_goodbye => true) # Unsubscribe multiple people at once
+    #
+    # @param [String, Array<String>] email address(es) of people to unsubscribe.
+    # @param [Hash] opts additional option to include when unsubscribing.
+    # @option opts [Boolean] :delete_member (false) completely delete the member from your list instead of just unsubscribing.
+    # @option opts [Boolean] :send_goodbye (true) send the goodbye email to the email addresses.
+    # @option opts [Boolean] :send_notify (false) send the unsubscribe notification email to the address defined in the list email notification settings.
+    # @return [Hash] contains 2 keys. :success contains the number of successful actions, :error a list of all errors.
+    def unsubscribe(emails, opts = {})
+      emails = [*emails]
+      params = { :method => "listBatchUnsubscribe", 
+                 :id => self.id }
+      params[:delete_member] = opts[:delete_member] if opts.has_key?(:delete_member)
+      params[:send_goodbye] = opts[:send_goodbye] if opts.has_key?(:send_goodbye)
+      params[:send_notify] = opts[:send_notify] if opts.has_key?(:send_notify)
+      params.merge!({ :emails => emails }.to_mailchimp)
+      response = post(params)
+      return { :success => response["success_count"],
+               :errors => response["errors"] }
+    end
+
+    # Will flag the email(s) as opted-out for all future mailing for this list
+    #
+    # @example Opt-out a single user
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   list.opt_out("glenn@rubypond.com") # Opt-out a single person
+    #
+    # @example Opt-out a list of users
+    #   emails = ["glenn@rubypond.com", "me@glenngillen.com"]
+    #   list.opt_out(emails) # Opt-out multiple people at once
+    #
+    # @param [String, Array<String>] email address(es) of people to opt-out.
+    # @return [Hash] contains 2 keys. :success contains the number of successful actions, :error a list of all errors.
+    def opt_out(emails)
+      emails = [*emails]
+      subscribe(emails.map{|email| { :email => email }})
+      unsubscribe(emails, :send_goodbye => false, :send_notify => false)
+    end
+
+    private
+      def self.reserved_keys
+        [:email, :type, :double_optin, :update_existing, :replace_interests, 
+         :send_welcome, :emails, :send_notify, :send_goodbye, :delete_member]
+      end
+
+      def subscribe_many(subscribers, opts = {})
+        if opts[:send_welcome]
+          subscribe_one_at_a_time(subscribers, opts)
+        else
+          subscribe_in_batches(subscribers, opts)
+        end
+      end
+
+      def batch_size
+        1000
+      end
+
+      def each_batch(subscribers, batch_size, &block) 
+        i = 0
+        while i < subscribers.size
+          start = Time.now
+          yield subscribers[i..(i+batch_size-1)], i
+          i += batch_size
+        end
+      end
+
+      def subscribe_in_batches(subscribers, opts)
+        cumulative_response = { :success => 0, :errors => [] }
+        each_batch(subscribers, batch_size) do |batch, i|
+          response = subscribe_one_batch(batch, opts)
+          cumulative_response[:success] += (response["success_count"] || 0)
+          cumulative_response[:errors] += (response["errors"] || [])
+        end
+        cumulative_response
+      end
+
+      def subscribe_one_batch(subscribers, opts)
+        params = { :id => self.id, :method => "listBatchSubscribe" }
+        params[:double_optin] = opts[:double_optin] if opts.has_key?(:double_optin)
+        params[:update_existing] = opts[:update_existing] if opts.has_key?(:update_existing)
+        params[:replace_interests] = opts[:replace_interests] if opts.has_key?(:replace_interests)
+        params.merge!({ :batch => subscribers }.to_mailchimp)
+        post(params, :timeout => timeout_for_batch(subscribers))
+      end
+
+      def timeout_for_batch(batch)
+        # 5 mins for a batch of 1000
+        ((batch.size.to_f / 1000) * (5 * 60)).to_i
+      end
+
+      def subscribe_one_at_a_time(subscribers, opts)
+        cumulative_response = { :success => 0, :errors => [] }
+        subscribers.each do |subscriber|
+          params = opts.merge(subscriber)
+          params.delete(:email)
+          if subscribe_one(subscriber[:email], params) == true
+            cumulative_response[:success] += 1
+          else
+            cumulative_response[:errors] << response["error"]
+          end
+        end
+        cumulative_response
+      end
+
+      def subscribe_one(email_address, opts = {})
+        params = {
+                  :type => opts.delete(:type),
+                  :double_optin => opts.delete(:double_optin),
+                  :update_existing => opts.delete(:update_existing),
+                  :replace_interests => opts.delete(:replace_interests),
+                  :send_welcome => opts.delete(:send_welcome),
+                  :email_address => email_address
+                 }
+        params.reject!{ |k,v| v.nil? }
+        merge_vars = { :merge_vars => opts }.to_mailchimp
+        params.merge!(merge_vars)
+        params.merge!(:method => "listSubscribe", :id => self.id)
+        post(params)
+      end
+  end
+end