netguru-hominid

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:

script/plugin install git://github.com/bgetting/hominid.git

Clone from the Github repository:

git clone git://github.com/bgetting/hominid.git

Use the GemPlugin:

config.gem "bgetting-hominid", :lib => 'hominid', :source => "http://gems.github.com"

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:

@hominid = Hominid.new

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:

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

For example, to subscribe someone to a mailing list at Mailchimp:

@hominid.subscribe(@list_id, "[e-mail]", {:FNAME => 'Bob', :LNAME => 'Smith'}, 'html')

To unsubscribe someone:

@hominid.unsubscribe(@list_id, "[e-mail]")

To update a list member:

@hominid.subscribe(@list_id, "[e-mail]", {:FNAME => 'Robert', :EMAIL => '[e-mail]'}, 'html', true)

or

@hominid.update_member(@list_id, "[e-mail]", {:FNAME => 'Robert', :EMAIL => '[e-mail]'})

Campaign methods are also supported. You can get all the campaigns for a particular list by:

@hominid.campaigns(@list_id)

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.