Hominid is a Ruby gem that provides a wrapper for interacting with the Mailchimp API.
Pull request Compare This branch is 223 commits ahead of ron:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



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


You will need a Mailchimp account. Once you have your Mailchimp account set up, you will need to generate an API key in order to get started using Hominid.


(sudo) gem install hominid


Please refer to the Mailchimp API Documentation for information about what methods are available, the arguments that can be passed to each method, and the output that the API will return. Start by creating a Hominid object:

h = Hominid::API.new('your_api_key')

You can also override the default configuration by passing in your own when initializing:

h = Hominid::API.new('your_api_key', {:secure => true, :timeout => 60})

Finally, and we're not sure why you would want to, but you can use the older versions of the API if you would like:

h = Hominid::API.new('your_api_key', {:api_version => '1.2'})

You can then run any of the methods that you find in the Mailchimp API Documentation against it. Simply convert the names to the more Ruby-like underscored versions (e.g. listUpdateMember becomes list_update_member).

MailChimp's API documentation states that several API methods (e.g. listUpdateMember, list_subscribe) require 'array' parameters. Hominid requires many (all?) of these parameters to be passed as *hashes*, not arrays – the examples below should all work as-is.

You do not need to pass your api_key to each method, as that is done automatically for you:

# list_id is a short hex string used internally by MailChimp to identify your lists (e.g. 'eceeae8b22')
# it's returned as the "id" member of the structure returned by the 'lists' call.
# Get all lists associated with this API key
# Subscribe 'joe@public.com', with merge variables 'FNAME' and 'LNAME', to the list identified by list_id
h.list_subscribe(list_id, 'joe@public.com', {'FNAME' => 'Joe', 'LNAME' => 'Public'}, 'html', false, true, true, false)
h.list_batch_subscribe(list_id, [{:EMAIL => 'joe@public.com', :EMAIL_TYPE => 'html'}, {:EMAIL => 'jane@doe.com', :EMAIL_TYPE => 'html'}])
h.campaign_create('regular', {:list_id => list_id, ...}, {:html => 'Campaign HTML content', ...})
h.template_add('template_name', 'Template HTML Code')
h.list_interest_grouping_add(list_id, 'Grouping Title', 'hidden', ['First Group', 'Second Group', 'Third Group'])
h.list_static_segment_add('Sample Static Segment')

The Mailchimp API now supports pagination for some methods, so certain methods will have the following response:

h.lists['total']        => 4
h.lists['data']         => outputs an array of your mailing lists
h.lists['data'].first   => {"id" => "XXXXXXX", "web_id" => 1234567, "name" => "My Mailing List", ...}

Please note that as of version 3.0.0 Hominid no longer includes support for the Mailchimp Export API.


Hominid includes some finder methods for campaigns (see Hominid::Campaign) and lists (see Hominid::List) to help with finding each of these resources:


Contributing to Hominid

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it

  • Fork the project

  • Start a feature/bugfix branch

  • Commit and push until you are happy with your contribution

  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.


Copyright © 2010 Brian Getting. See LICENSE.txt for further details.