Note: The official Mailchimp gem is a better alternative to Hominid if you are starting a new project. There is a lot less data-bludgeoning because it uses JSON rather than XML, and it also includes support for the Mandrill API as well.

Hominid <img src=“http://travis-ci.org/terra-firma/hominid.png” /> <img src=“https://gemnasium.com/terra-firma/hominid.png” alt=“Dependency Status” />

Hominid is a Ruby gem that provides a wrapper for interacting with Mailchimp’s MC, STS and Export API’s. Check out the Mandrill gem if you are interested in working with the Mandrill API.

Requirements

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 (or you can use OAuth2 as well).

Installation

(sudo) gem install hominid

Usage

MCAPI

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.
h.get_account_details
# Get all lists associated with this API key
h.lists
# Subscribe '[email protected]', with merge variables 'FNAME' and 'LNAME', to the list identified by list_id
h.list_subscribe(list_id, '[email protected]', {'FNAME' => 'Joe', 'LNAME' => 'Public'}, 'html', false, true, true, false)
h.list_batch_subscribe(list_id, [{:EMAIL => '[email protected]', :EMAIL_TYPE => 'html'}, {:EMAIL => '[email protected]', :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 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", ...}

Finder Methods

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

h.find_list_by_name('my_mailing_list')
h.find_list_id_by_name('my_mailing_list')
h.find_campaigns_by_list_name('my_mailing_list')

STS API

Please refer to the Mailchimp STS 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:

s = Hominid::STS.new('your_api_key', {:secure => true})

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

s.list_verified_email_addresses
s.verify_email_address('[email protected]')
s.send_email({:to_email => ['[email protected]'], :text => 'Hello World!'}, false, true)
s.get_send_quota

Note that MailChimp will return an error if you attempt to make STS API calls on an account without Amazon SES integration.

Export API

Please refer to the Mailchimp Export 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:

e = Hominid::Export.new('your_api_key', {:secure => true})

You can then run the following methods:

e.list('list_id')
e.campaign_subscriber_activit('campaign_id')

Submitting an Issue

We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn’t already been submitted. You can indicate support for an existing issue by voting it up. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. Ideally, a bug report should include a pull request with failing specs.

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.