h1. Hominid

Hominid is a Ruby gem for interacting with the "Mailchimp API":http://www.mailchimp.com/api/1.2/.

h2. Installation

Install the gem:

<pre><code>sudo gem install hominid</code></pre>

In your @environment.rb@ file:

<pre><code>config.gem "hominid"</code></pre>

You can also install Hominid as a Rails plugin:

<pre><code>script/plugin install git://github.com/bgetting/hominid.git</code></pre>

h2. Setup

Hominid expects to find a config file at @/config/hominid.yml@ in a Rails application, but you can also pass a hash of config options when creating a new Hominid object (thanks to "ron":http://github.com/ron).

You will also need to create a Mailchimp account to get your API key (available at "http://admin.mailchimp.com/account/api/":http://admin.mailchimp.com/account/api/) to configure a Hominid object. 

h2. Example

To interact with the Mailchimp API, simply create a new Hominid object:

<pre><code>@hominid = Hominid.new</code></pre>

_or_

<pre><code>@hominid = Hominid.new({:username => 'USERNAME', :password => 'PASSWORD', :api_key => 'API_KEY', :send_goodbye => false, :send_notify => false, :double_opt => false})</code></pre>

You will need to have the @list ID@ of the mailing list you want to work with. You can find the @list ID@ of a list by:

<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>

To subscribe:

<pre><code>@hominid.subscribe(@list_id, "email@example.com", :user_info => {:FNAME => 'Bob', :LNAME => 'Smith'}, :email_type => 'html')</code></pre>

To unsubscribe:

<pre><code>@hominid.unsubscribe(@list_id, "email@example.com")</code></pre>

To update a member:

<pre><code>@hominid.subscribe(@list_id, "email@example.com", :user_info => {:FNAME => 'Robert', :EMAIL => 'another@example.com'}, :email_type => 'html', :update_existing => 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. Recently, "ron":http://github.com/ron and "netguru":http://github.com/netguru have also provided useful changes as well.

I encourage anyone using this gem to please fork it, improve it, and send me a pull request. I typically only use this gem in a minimal capacity, primarily for just managing whether or not a user is signed up for a mailing list. I do not intend to continue maintaining the "Acts As Mailchimp":http://github.com/bgetting/acts_as_mailchimp in the future, since I personally prefer to just use the Hominid gem.

So please, help us to improve this gem!

Copyright (c) 2009 Brian Getting, released under the MIT license.