netguru-hominid 1.1.3

data/README.textile

@@ -0,0 +1,71 @@
+h1. Hominid
+
+Hominid is a GemPlugin wrapper to the "Mailchimp API":http://www.mailchimp.com/api/1.2/.
+
+h2. Installation
+
+There are a few options for installing Hominid.
+
+Install as a Rails plugin:
+
+<pre><code>script/plugin install git://github.com/bgetting/hominid.git</code></pre>
+
+Clone from the Github repository:
+
+<pre><code>git clone git://github.com/bgetting/hominid.git</code></pre>
+
+Use the GemPlugin:
+
+<pre><code>config.gem "bgetting-hominid", :lib => 'hominid', :source => "http://gems.github.com"</code></pre>
+
+h2. Configuration
+
+Please note that Hominid expects to find a configuration file at @/config/hominid.yml@. If you are using Hominid as a GemPlugin, you will need to be sure and create this file. If you are using Hominid as a normal Rails plugin, this file will be created automatically when the plugin is installed. You will need to create a Mailchimp account and put your API key (available at "http://admin.mailchimp.com/account/api/":http://admin.mailchimp.com/account/api/) into the configuration file. 
+
+h2. Example
+
+To interact with the Mailchimp API, simply create a new Hominid object:
+
+<pre><code>@hominid = Hominid.new</code></pre>
+
+First, locate the mailing list that you are going to be working with. If you know the mailing list ID, then you can use that directly. Or you can find a particular list by name using:
+
+<pre><code>
+def find_list_id(list_name)
+  mailing_lists = @hominid.lists
+  unless mailing_lists.nil?
+    @list_id = mailing_lists.find {|list| list["name"] == list_name}["id"]
+  end
+end
+</code></pre>
+
+For example, to subscribe someone to a mailing list at Mailchimp:
+
+<pre><code>@hominid.subscribe(@list_id, "email@example.com", {:FNAME => 'Bob', :LNAME => 'Smith'}, 'html')</code></pre>
+
+To unsubscribe someone:
+
+<pre><code>@hominid.unsubscribe(@list_id, "email@example.com")</code></pre>
+
+To update a list member:
+
+<pre><code>@hominid.subscribe(@list_id, "email@example.com", {:FNAME => 'Robert', :EMAIL => 'another@example.com'}, 'html', true)</code></pre>
+
+_or_
+
+<pre><code>@hominid.update_member(@list_id, "email@example.com", {:FNAME => 'Robert', :EMAIL => 'another@example.com'})</code></pre>
+
+Campaign methods are also supported. You can get all the campaigns for a particular list by:
+
+<pre><code>@hominid.campaigns(@list_id)</code></pre>
+
+Leave the @@list_id@ out and it will return all the campaigns for your Mailchimp account.
+
+
+h2. Other Stuff
+
+For the most part, this whole thing was an attempt to optimize the acts_as_mailchimp plugin, and incorporates all the great work from "C.G. Brown":http://www.projectlocker.com/ and "Kelly Mahan":http://digimedia.com/, as well as "Matthew Carlson":http://mandarinsoda.com/, whose plugin inspired nearly all of this work.
+
+The Acts_As_Mailchimp plugin will be updated to utilize Hominid, so that there is still a way to add simple "acts_as" methods to a model. However, since Hominid is such a thin wrapper I encourage people to start experimenting with using the other methods to integrate newsletter marketing natively into their apps. Mailchimp put a lot of work into their API, so take advantage of it and make something cool!
+
+Copyright (c) 2009 Brian Getting, released under the MIT license.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 1
+:patch: 2

data/lib/hominid.rb

@@ -0,0 +1,327 @@
+require 'xmlrpc/client'
+
+class Hominid
+  
+  # MailChimp API Documentation: http://www.mailchimp.com/api/1.2/
+  MAILCHIMP_API = "http://api.mailchimp.com/1.2/"
+  
+  def initialize
+    load_monkey_brains
+    @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+    return self
+  end
+  
+  def load_monkey_brains
+    config = YAML.load(File.open("#{RAILS_ROOT}/config/hominid.yml"))[RAILS_ENV].symbolize_keys
+    @chimpUsername  = config[:username].to_s
+    @chimpPassword  = config[:password].to_s
+    @api_key        = config[:api_key]
+    @send_goodbye   = config[:send_goodbye]
+    @send_notify    = config[:send_notify]
+    @double_opt     = config[:double_opt]
+  end
+  
+  ## Security related methods
+  
+  def add_api_key
+    begin
+      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+      @chimpApi.call("apikeyAdd", @chimpUsername, @chimpPassword, @api_key)
+    rescue
+      false
+    end
+  end
+  
+  def expire_api_key
+    begin
+      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+      @chimpApi.call("apikeyExpire", @chimpUsername, @chimpPassword, @api_key)
+    rescue
+      false
+    end
+  end
+  
+  def api_keys(include_expired = false)
+    begin
+      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+      @api_keys = @chimpApi.call("apikeys", @chimpUsername, @chimpPassword, @api_key, include_expired)
+    rescue
+      return nil
+    end
+  end
+  
+  ## Campaign related methods
+  
+  def campaign_content(campaign_id)
+    # Get the content of a campaign
+    begin
+      @content = @chimpApi.call("campaignContent", @api_key, campaign_id)
+    rescue
+      return nil
+    end
+  end
+  
+  def campaigns(filters = {}, start = 0, limit = 50)
+    # Get the campaigns for this account
+    # API Version 1.2 requires that filters be sent as a hash
+    # Available options for the filters hash are:
+    #
+    #   :campaign_id    = (string)  The ID of the campaign you wish to return. 
+    #   :list_id        = (string)  Show only campaigns with this list_id. 
+    #   :folder_id      = (integer) Show only campaigns from this folder.
+    #   :from_name      = (string)  Show only campaigns with this from_name.
+    #   :from_email     = (string)  Show only campaigns with this from_email.
+    #   :title          = (string)  Show only campaigns with this title.
+    #   :subject        = (string)  Show only campaigns with this subject.
+    #   :sedtime_start  = (string)  Show campaigns sent after YYYY-MM-DD HH:mm:ss.
+    #   :sendtime_end   = (string)  Show campaigns sent before YYYY-MM-DD HH:mm:ss.
+    #   :subject        = (boolean) Filter by exact values, or search within content for filter values.
+    begin
+      @campaigns = @chimpApi.call("campaigns", @api_key, filters, start, limit)
+    rescue
+      return nil
+    end
+  end
+  
+  def create_campaign(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
+    # Create a new campaign
+    begin
+      @campaign = @chimpApi.call("campaignCreate", @api_key, type, options, content, segment_options, type_opts)
+    rescue
+      return nil
+    end
+  end
+  
+  def delete_campaign(campaign_id)
+    # Delete a campaign
+    begin
+      @campaign = @chimpApi.call("campaignDelete", @api_key, campaign_id)
+    rescue
+      false
+    end
+  end
+  
+  def replicate_campaign(campaign_id)
+    # Replicate a campaign (returns ID of new campaign)
+    begin
+      @campaign = @chimpApi.call("campaignReplicate", @api_key, campaign_id)
+    rescue
+      false
+    end
+  end
+  
+  def schedule_campaign(campaign_id, time = "#{1.day.from_now}")
+    # Schedule a campaign
+    ## TODO: Add support for A/B Split scheduling
+    begin
+      @chimpApi.call("campaignSchedule", @api_key, campaign_id, time)
+    rescue
+      false
+    end
+  end
+  
+  def send_now(campaign_id)
+    # Send a campaign
+    begin
+      @chimpApi.call("campaignSendNow", @api_key, campaign_id)
+    rescue
+      false
+    end
+  end
+  
+  def send_test(campaign_id, emails = {})
+    # Send a test of a campaign
+    begin
+      @chimpApi.call("campaignSendTest", @api_key, campaign_id, emails)
+    rescue
+      false
+    end
+  end
+  
+  def templates
+    # Get the templates
+    begin
+      @templates = @chimpApi.call("campaignTemplates", @api_key)
+    rescue
+      return nil
+    end
+  end
+  
+  def update_campaign(campaign_id, name, value)
+    # Update a campaign
+    begin
+      @chimpApi.call("campaignUpdate", @api_key, campaign_id, name, value)
+    rescue
+      false
+    end
+  end
+  
+  def unschedule_campaign(campaign_id)
+    # Unschedule a campaign
+    begin
+      @chimpApi.call("campaignUnschedule", @api_key, campaign_id)
+    rescue
+      false
+    end
+  end
+  
+  ## Helper methods
+  
+  def html_to_text(content)
+    # Convert HTML content to text
+    begin
+      @html_to_text = @chimpApi.call("generateText", @api_key, 'html', content)
+    rescue
+      return nil
+    end
+  end
+  
+  def convert_css_to_inline(html, strip_css = false)
+    # Convert CSS styles to inline styles and (optionally) remove original styles
+    begin
+      @html_to_text = @chimpApi.call("inlineCss", @api_key, html, strip_css)
+    rescue
+      return nil
+    end
+  end
+  
+  ## List related methods
+  
+  def lists
+    # Get all of the lists for this mailchimp account
+    begin
+      @lists = @chimpApi.call("lists", @api_key)
+    rescue
+      return nil
+    end
+  end
+  
+  def create_group(list_id, group)
+    # Add an interest group to a list
+    begin
+      @chimpApi.call("listInterestGroupAdd", @api_key, list_id, group)
+    rescue
+      false
+    end
+  end
+  
+  def create_tag(list_id, tag, name, required = false)
+    # Add a merge tag to a list
+    begin
+      @chimpApi.call("listMergeVarAdd", @api_key, list_id, tag, name, required)
+    rescue
+      false
+    end
+  end
+  
+  def delete_group(list_id, group)
+    # Delete an interest group for a list
+    begin
+      @chimpApi.call("listInterestGroupDel", @api_key, list_id, group)
+    rescue
+      false
+    end
+  end
+  
+  def delete_tag(list_id, tag)
+    # Delete a merge tag and all its members
+    begin
+      @chimpApi.call("listMergeVarDel", @api_key, list_id, tag)
+    rescue
+      false
+    end
+  end
+  
+  def groups(list_id)
+    # Get the interest groups for a list
+    begin
+      @groups = @chimpApi.call("listInterestGroups", @api_key, list_id)
+    rescue
+      return nil
+    end
+  end
+  
+  def member(list_id, email)
+    # Get a member of a list
+    begin
+      @member = @chimpApi.call("listMemberInfo", @api_key, list_id, email)
+    rescue
+      return nil
+    end
+  end
+  
+  def members(list_id, status = "subscribed", since = "2000-01-01 00:00:00", start = 0, limit = 100)
+    # Get members of a list based on status
+    # Select members based on one of the following statuses:
+    #   'subscribed'
+    #   'unsubscribed'
+    #   'cleaned'
+    #   'updated'
+    #
+    # Select members that have updated their status or profile by providing
+    # a "since" date in the format of YYYY-MM-DD HH:MM:SS
+    # 
+    begin
+      @members = @chimpApi.call("listMembers", @api_key, list_id, status, since, start, limit)
+    rescue
+      return nil
+    end
+  end
+  
+  def merge_tags(list_id)
+    # Get the merge tags for a list
+    begin
+      @merge_tags = @chimpApi.call("listMergeVars", @api_key, list_id)
+    rescue
+      return nil
+    end
+  end
+  
+  def subscribe(list_id, email, user_info = {}, email_type = "html", update_existing = true, replace_interests = true, double_opt_in = nil)
+    # Subscribe a member
+    begin
+      @chimpApi.call("listSubscribe", @api_key, list_id, email, user_info, email_type, double_opt_in || @double_opt, update_existing, replace_interests)
+    rescue
+      false
+    end
+  end
+  
+  def subscribe_many(list_id, subscribers)
+    # Subscribe a batch of members
+    # subscribers = {:EMAIL => 'example@email.com', :EMAIL_TYPE => 'html'} 
+    begin
+      @chimpApi.call("listBatchSubscribe", @api_key, list_id, subscribers, @double_opt, true)
+    rescue
+      false
+    end
+  end
+  
+  def unsubscribe(list_id, current_email)
+    # Unsubscribe a list member
+    begin
+      @chimpApi.call("listUnsubscribe", @api_key, list_id, current_email, true, @send_goodbye, @send_notify)
+    rescue
+      false
+    end
+  end
+  
+  def unsubscribe_many(list_id, emails)
+    # Unsubscribe an array of email addresses
+    # emails = ['first@email.com', 'second@email.com'] 
+    begin
+      @chimpApi.call("listBatchUnsubscribe", @api_key, list_id, emails, true, @send_goodbye, @send_notify)
+    rescue
+      false
+    end
+  end
+  
+  def update_member(list_id, current_email, user_info = {}, email_type = "")
+    # Update a member of this list
+    begin
+      @chimpApi.call("listUpdateMember", @api_key, list_id, current_email, user_info, email_type, true)
+    rescue
+      false
+    end
+  end
+
+end

data/test/hominid_test.rb

@@ -0,0 +1,11 @@
+require 'test_helper'
+
+class HominidTest < ActiveSupport::TestCase
+  # Replace this with your real tests.
+  test "the truth" do
+    assert true
+  end
+  
+  ## TODO: Write tests to verify each method
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'active_support'
+require 'active_support/test_case'

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+name: netguru-hominid
+version: !ruby/object:Gem::Version 
+  version: 1.1.3
+platform: ruby
+authors: 
+- Brian Getting
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-28 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Hominid is a Rails GemPlugin for interacting with the Mailchimp API
+email: brian@terra-firma-design.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- README.textile
+- VERSION.yml
+- lib/hominid.rb
+- test/hominid_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/bgetting/hominid
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Hominid is a Rails GemPlugin for interacting with the Mailchimp API
+test_files: []
+