Skip to content
Hominid is a Ruby gem that provides a wrapper for interacting with the Mailchimp API.
Find file
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 ='your_api_key')

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

h ='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 ='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. You do not need to pass your api_key to each method, as that is done automatically for you:

h.list_subscribe('XXXXXXXXXX', '', [], 'html', false, true, true, false)
h.list_batch_subscribe('XXXXXXXXXX', [{:EMAIL => '', :EMAIL_TYPE => 'html'}, {:EMAIL => '', :EMAIL_TYPE => 'html'}])
h.campaign_create('regular', {:list_id => 'XXXXXXXXXX', ...}, {:html => 'Campaign HTML content', ...})
h.template_add('template_name', 'Template HTML Code')
h.list_interest_grouping_add('XXXXXXXXXX', '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.

Something went wrong with that request. Please try again.