h1. Hominid

Hominid is a Ruby gem that provides a wrapper for interacting with the "Mailchimp":http://eepurl.com/ew8J email marketing service API ("version 1.2":http://www.mailchimp.com/api/1.2/).

h2. Installation

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

Hominid is hosted at "Gemcutter":http://gemcutter.org. Be sure that you have the Gemcutter gem installed if you are having trouble installing Hominid:

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

h2. Requirements

You will need a "Mailchimp":http://eepurl.com/ew8J account. Once you have your Mailchimp account set up, you will need to "generate an API key":http://admin.mailchimp.com/account/api/ in order to get started using Hominid.

h2. Usage

Hominid is intended to be a complete Ruby wrapper for working with the Mailchimp API. As of release 2.0.2, all methods available from the Mailchimp API (Version 1.2) are available. Please note in order to use some methods you will need to have "A.I.M. Reports":https://admin.mailchimp.com/account/addons installed on your Mailchimp account.

You will need to pass your Mailchimp API key to get started:

<pre><code>h = Hominid::Base.new({:api_key => API_KEY})</code></pre>

You can also pass in any other config options that you would like to change from the defaults. Take a look at @Hominid::Base@ to see what the default values are.

Once you have created a Hominid object, you can begin interacting with the Mailchimp account that your API key is associated with.

h3. Working with Lists

We have provided some finder methods to make working with your mailing lists easier:

<pre><code>lists = h.lists
list = h.find_list_by_name("Mailing List Name")
list = h.find_list_by_id("List ID")
list = h.find_list_by_web_id("List Web ID")</code></pre>

There are also finders for easily getting at List ID's, which are required for nearly all the list methods:

<pre><code>list_id = h.find_list_id_by_name("Mailing List Name")
list_id_ = h.find_list_id_by_web_id("List Web ID")</code></pre>

This means that you can _(for example)_ subscribe someone to a particular mailing list:

<pre><code>h.subscribe(h.find_list_id_by_name("Mailing List Name"), "email@domain.com", {:FNAME => "Bob", :LNAME => "Smith"}, {:email_type => 'html'})</code></pre>

Or to update a subscriber to a particular list:

<pre><code>h.update_member(h.find_list_id_by_name("Mailing List Name"), "old_email@domain.com", {:EMAIL => "new_email_@domain.com"}, 'html')</code></pre>

Take a look at @Hominid::List@ to see the methods that are available for interacting with your lists.

h3. Working with Campaigns

We have provided some finder methods to make working with your campaigns easier:

<pre><code>campaigns = h.campaigns
campaigns = h.find_campaigns_by_list_name("Mailing List Name")
campaigns = h.find_campaigns_by_list_id("Mailing List ID")
campaigns = h.find_campaigns_by_type("regular")
campaign = h.find_campaign_by_id("Campaign ID")
campaign = h.find_campaign_by_title("Campaign Title")</code></pre>

To create a new campaign, use the @create_campaign@ method:

<pre><code>new_campaign = h.create_campaign(...)</code></pre>

Take a look at @Hominid::Campaign@ to see the methods that are available for interacting with your campaigns.

h3. Mailchimp Helper Methods

There are a series of helper methods that are also made available with the Hominid gem. For example, to retrieve information about the Mailchimp account associated with your API key, simply:

<pre><code>account_details_ = h.account_details</code></pre>

In this case, the @account_details@ object can be accessed like:

<pre><code>account_details.contact.company
account_details.orders</code></pre>

Take a look at @Hominid::Helper@ to see the helper methods that are available.

h3. Mailchimp Security Methods

There are a couple of security methods that are also made available with the Hominid gem. These are primarily used for dealing with API keys, and require your Mailchimp account username and password:

<pre><code>h.api_keys('username', 'password')</code></pre>

Take a look at @Hominid::Security@ to see the security methods that are available.

h2. Contributors

Hominid is maintained by "Brian Getting":http://terra-firma-design.com. A very special thank-you to "Michael Strüder":http://github.com/mikezter for all of his hard work. Also, Hominid wouldn't be anywhere near as awesome as it is today without fantastic contributions and inspiration from:

* "Alan Harper":http://github.com/aussiegeek
* "Will":http://github.com/willinfront
* "Ben Woosley":http://github.com/Empact
* "banker":http://github.com/banker
* "Kristoffer Renholm":http://github.com/renholm
* "Wiktor Schmidt":http://github.com/netguru
* "ron":http://github.com/ron
* "Matthew Carlson":http://mandarinsoda.com/
* "Kelly Mahan":http://digimedia.com/
* "C.G. Brown":http://www.projectlocker.com/
* "Bill Abney":http://github.com/babney
* "David Rice":http://github.com/davidjrice

h2. Note on Patches/Pull Requests

# Fork the project.
# Make your feature addition or bug fix.
# Add tests for it. This is important so I don't break it in a future version unintentionally.
# Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
# Send me a pull request. Bonus points for topic branches.

h2. Copyright

Copyright (c) 2009 Brian Getting. See LICENSE for details.