Hominid

Hominid is a Ruby gem for interacting with the Mailchimp API.

Installation

Install the gem:

gem sources -a http://gems.github.com
sudo gem install bgetting-hominid

In your environment.rb file:

config.gem "bgetting-hominid", :lib => 'hominid', :source => "http://gems.github.com"

You can also install Hominid as a Rails plugin:

script/plugin install git://github.com/bgetting/hominid.git

Setup

Hominid expects to find a config file at /config/hominid.yml in a Rails application, but you can also pass a hash of config options when creating a new Hominid object (thanks to ron).

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

Example

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

@hominid = Hominid.new

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

@hominid.subscribe(@list_id, "email@example.com", :user_info => {:FNAME => 'Bob', :LNAME => 'Smith'}, :email_type => 'html')

To unsubscribe:

@hominid.unsubscribe(@list_id, "email@example.com")

To update a member:

@hominid.subscribe(@list_id, "email@example.com", :user_info => {:FNAME => 'Robert', :EMAIL => 'another@example.com'}, :email_type => 'html', :update_existing => true)

@hominid.update_member(@list_id, "email@example.com", {:FNAME => 'Robert', :EMAIL => 'another@example.com'})

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!

francisd/hominid

Hominid

Installation

Setup

Example

Other Stuff