= 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/]).

== Installation

  sudo gem install hominid

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

  sudo gem install gemcutter

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

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

  h = Hominid::Base.new({:api_key => API_KEY})

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.

=== Working with Lists

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

  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:

  list_id = h.find_list_id_by_name("Mailing List Name")
  list_id_ = h.find_list_id_by_web_id("List Web ID")

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

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

Or to update a subscriber to a particular list:

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

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

=== Working with Campaigns

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

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

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

  new_campaign = h.create_campaign(...)

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

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

  account_details_ = h.account_details

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

  account_details.contact.company
  account_details.orders

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

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

  h.api_keys('username', 'password')

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

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

== Note on Patches/Pull Requests

1. Fork the project.
2. Make your feature addition or bug fix.
3. Add tests for it. This is important so I don't break it in a future version unintentionally.
4. 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)
5. Send me a pull request. Bonus points for topic branches.

== Copyright

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