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 _(or you can use OAuth2 as well)_.
(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.
h.get_account_details
# Get all lists associated with this API key
h.lists
# 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.
You can make use of MailChimp’s STS API by creating an STS object:
sts = Hominid::STS.new('your_api_key')
All of the configuration options available above can be included here, as well:
sts = Hominid::STS.new('your_api_key', {:secure => true, :timeout => 60})
You can run any of the commands listed in the STS API Documentation:
sts.list_verified_email_addresses sts.verify_email_address('joe@public.com') sts.send_email({:to_email => ['joe@public.com'], :text => 'Hello World!'}, false, true) sts.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.
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')
<img src=“http://travis-ci.org/terra-firma/hominid.png” />
-
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.