h1. Hominid

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

h2. Installation

<pre><code>sudo gem install hominid, :version => '>= 2.0.0', :source => "http://gemcutter.org"</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
gem tumble</code></pre>

h2. Configuration

You will need to create a "Mailchimp":http://www.mailchimp.com/signup account and get your API key (available at http://admin.mailchimp.com/account/api/) in order to get started.

If you are using Hominid inside a Rails application, you can create a config file at @/config/hominid.yml@ with your Mailchimp account information and basic configuration options:

<pre><code>development:
 username: USERNAME
 password: PASSWORD
 api_key: API KEY
 send_goodbye: false
 send_notify: false
 double_opt: false

...</code></pre>

Run @rake hominid:config@ from within a Rails app to create an empty config file.
Note: You will need to <pre><code>require 'hominid'</code></pre> in your @Rakefile@ to make this rake task available to your application.

h2. Usage

Not all API methods are supported (yet). Currently there are classes for working with lists (_Hominid::List_), campaigns (_Hominid::Campaign_) and accessing the helper methods (_Hominid::Helper_).

h3. Working with Lists

The _Hominid::List_ class is available for working finding lists and working with particular lists. See _Hominid::List_ for more information.

h4. List Finder Methods

There are finder methods for working with lists. Refer to _Hominid::List_ to see the other finders availables.

<pre><code>lists = Hominid::List.all</code></pre>

<pre><code>list = Hominid::List.find_by_name("List Name")</code></pre>

<pre><code>list = Hominid::List.find(id_or_web_id)</code></pre>

h4. Subscribing

To subscribe a person or persons to a Mailchimp list:

<pre><code>list.subscribe("sample@emailaddress.com")</code></pre>

<pre><code>list.subscribe_many([{:EMAIL => 'sample@emailaddress.com', :EMAIL_TYPE => 'html'}, {:EMAIL => 'another@emailaddress.com', :EMAIL_TYPE => 'html'}])</code></pre>

h4. Unsubscribing

To unsubscribe a person or persons from a Mailchimp list:

<pre><code>list.unsubscribe("sample@emailaddress.com")</code></pre>

<pre><code>list.unsubscribe_many(['sample@emailaddress.com', 'another@emailaddress.com'])</code></pre>

h4. Updating

In the following example, we will be changing a person's email address on the Mailchimp list from @sample@ to @another@:

<pre><code>list.update_member('sample@emailaddress.com', {:EMAIL => 'another@emailaddress.com'}, 'html')</code></pre>

You can also updated other attributes by including the MERGE_VARS that you want to change, such as @EMAIL@, @FNAME@, @LNAME@ and @INTERESTS@. Get a list of merge tags for a particular list by running @list.merge_tags@.

h3. Working with Campaigns

The _Hominid::Campaign_ class provides methods for working with a campaigns.

h4. Campaign Finder Methods

There are finder methods for campaigns as well. Refer to _Hominid::Campaign_ to see the other finders available.

<pre><code>campaigns = Hominid::Campaign.all</code></pre>

<pre><code>campaigns = Hominid::Campaign.find_by_list_name("List Name")</code></pre>

h4. Creating a Campaign

You can create new campaigns using Hominid as well. Please refer to the documentation in _Hominid::Base_ for more information about the options available when creating a new campaign.

<pre><code>new_campaign = Hominid::Campaign.create('regular', options, content, segment_opts, type_opts)</code></pre>

h4. Schedule a Campaign

As an example of how to work with a particular campaign, use the _Hominid::Campaign_ class. Extending from the previous example, since the _#create_campaign_ method returns the ID of the created campaign, we can use it to instantiate the _Hominid::Campaign_ class and schedule our new campaign to go be delivered 2 days from now:

<pre><code>campaign = Hominid::Campaign.new(:id => new_campaign)</code></pre>

<pre><code>campaign.schedule_campaign(2.days.from_now)</code></pre>

h3. Helper Methods

The _Hominid::Helper_ class provides a way to access the helper methods for the Mailchimp API. For example, to create a new folder for filing campaigns:

<pre><code>folder = Hominid::Helper.create_folder("Folder Name")</code></pre>

h2. Syncing Your Application

If you are integrating an application with Mailchimp, Hominid will provide a way for your app to connect with your Mailchimp account. However, it does not provide a way for Mailchimp to connect to your application, which is why Mailchimp has implemented "web hooks":http://www.mailchimp.com/api/webhooks/.

The _Hominid::Webhook class helps with receiving <tt>POST</tt> data from a Mailchimp webhook:

<pre><code>hook = Hominid::Webhook.new(params)
case hook.event
when "subscribe"
  user = User.find_by_email(hook.email)
  user.opted_in = true
  user.save
when "unsubscribe"
  user = User.find_by_email(hook.email)
  user.opted_in = false
  user.save
when "profile"
  user = User.find_by_email(hook.email)
  user.first_name = hook.first_name
  user.last_name = hook.last_name
  user.email_type = hook.email_type
  user.save
when "upemail"
  user = User.find_by_email(hook.old_email)
  user.email = hook.new_email
  user.save
end</code></pre>

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/

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.