Hominid Gem Version 2.0

We’ve finally gotten around to doing some updating on the Ruby gem that we maintain called Homind. Hominid provides a wrapper for the Mailchimp API, allowing developers to easily integrate with Mailchimp’s email marketing service. Along with updating the gem, we have also moved it to Gemcutter since Github is no longer hosting gems.

Installing Hominid

To install the Hominid gem, be sure that you have installed the Gemcutter gem, or that Gemcutter is available as one of your gem sources. The easiest way is to simply install the Gemcutter gem:

sudo gem install gemcutter
gem tumble

This will add Gemcutter to your list of gem sources, and sets up to install gems from Gemcutter. To install the Hominid gem, simply enter:

sudo gem install hominid

Configuration

The upgrade to version 2.0 is essentially a complete overhaul, thanks to some fantastic help from Micheal Struder, and is no longer available as a Ruby on Rails plugin. From here on out, Hominid will just a pure Ruby gem. Detailed documentation is available, but getting set up with your Rails application requires that you set the gem dependency in your environment.rb file.

config.gem "hominid", :version => '>= 2.0.0', :source => "http://gemcutter.org"

It is also convenient to set up a configuration file with your Mailchimp account information at config/hominid.yml. Refer to the Hominid documentation for more information on setting up that YAML file.

Simple Usage

There has been a lot of refactoring with the gem, which makes usage a slight bit different than with previous versions. The gem has been changed from a single class to a module, and we have implemented the Hominid::List class (for working with lists) and the Hominid::Campaign class (for working with campaigns).

To find a particular list that you want to work with, simply use one of the finder methods for the List class:

list = Hominid::List.find_by_name('mailing list name')

Once you’ve found your list, let’s say that you want to subscribe someone to your mailing list. Use the subscribe method in this instance:

list.subscribe('my@emailaddress.com')

Or, perhaps you want to unsubscribe someone from that email list, in which case you would use the unsubscribe method:

list.unsubscribe('my@emailaddress.com'

Finally, you may want to updated someone’s information in your mailing list, which is done using the @update_member) method:

list.update_member('my@emailaddress.com', {:EMAIL => 'another@emailaddress.com'}, 'html')

You can send other attributes in the hash, such as :FNAME to change other attributes of the persons subscription, aside from just their email address.

Documentation

We are doing the best that we can do document the usage of the Hominid gem. Don’t forget to visit the gem documentation to get a better idea of how to use the new gem. We are hoping that more and more people will get involved with helping us to improve this gem. There are quite a few API methods that have not been implemented yet, primarily since we don’t use them much. However, the gem is primed and ready to become a complete wrapper for the Mailchimp API, and any contributions are greatly appreciated.

Published by Brian Getting on Thursday, October 22, 2009.
Subscribe to our blog RSS feed.