renholm / hominid

Hominid is a Rails GemPlugin for interacting with the Mailchimp API

Hominid

Hominid is a GemPlugin wrapper to the Mailchimp API.

Installation

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"

Configuration

You can either use a master config file, which Hominid expects to find at /config/hominid.yml or (thanks to ron) you can pass a hash of config options when calling Hominid. If you are using Hominid as a Rails plugin, the config file will be created for you. If you are using Hominid as a gem, you will need to create the config file.

You will also need to create a Mailchimp account to get your API key (available at http://admin.mailchimp.com/account/api/) for configuration.

Example

To interact with the Mailchimp API, simply create a new Hominid object:

@hominid = Hominid.new

or

@hominid = Hominid.new({:username => 'USERNAME', :password => 'PASSWORD', :api_key => 'API_KEY', :send_goodbye => false, :send_notify => false, :double_opt => false})

You will need to have the list ID of the mailing list you want to work with. You can find the list ID of a list by:

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

To subscribe someone:

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

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 and Kelly Mahan, as well as Matthew Carlson, whose plugin inspired nearly all of this work. Recently, ron and netguru have also provided useful changes as well.

I encourage anyone using this gem to please fork it, improve it, and send me a pull request. I typically only use this gem in a minimal capacity, primarily for just managing whether or not a user is signed up for a mailing list. I do not intend to continue maintaining the Acts As Mailchimp in the future, since I personally prefer to just use the Hominid gem.

So please, help us to improve this gem!

Copyright © 2009 Brian Getting, released under the MIT license.