Hominid is a Ruby gem that provides a wrapper for interacting with the Mailchimp email marketing service API (version 1.2).
sudo gem install hominid
Hominid is hosted at Gemcutter. Be sure that you have the Gemcutter gem installed if you are having trouble installing Hominid:
sudo gem install gemcutter
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.
Hominid is intended to be a complete Ruby wrapper for working with the Mailchimp API. As of release 2.0.2, all methods available from the Mailchimp API (Version 1.2) are available. Please note in order to use some methods you will need to have A.I.M. Reports installed on your Mailchimp account.
You will need to pass your Mailchimp API key to get started:
h = Hominid::Base.new({:api_key => API_KEY})
You can also pass in any other config options that you would like to change from the defaults. Take a look at Hominid::Base to see what the default values are.
Once you have created a Hominid object, you can begin interacting with the Mailchimp account that your API key is associated with.
We have provided some finder methods to make working with your mailing lists easier:
lists = h.lists
list = h.find_list_by_name("Mailing List Name")
list = h.find_list_by_id("List ID")
list = h.find_list_by_web_id("List Web ID")</code></pre>
There are also finders for easily getting at List ID’s, which are required for nearly all the list methods:
list_id = h.find_list_id_by_name("Mailing List Name") list_id_ = h.find_list_id_by_web_id("List Web ID")
This means that you can _(for example)_ subscribe someone to a particular mailing list:
h.subscribe(h.find_list_id_by_name("Mailing List Name"), "email@domain.com", {:FNAME => "Bob", :LNAME => "Smith"}, {:email_type => 'html'})
Or to update a subscriber to a particular list:
h.update_member(h.find_list_id_by_name("Mailing List Name"), "old_email@domain.com", {:EMAIL => "new_email_@domain.com"}, 'html')
Take a look at Hominid::List to see the methods that are available for interacting with your lists.
We have provided some finder methods to make working with your campaigns easier:
campaigns = h.campaigns campaigns = h.find_campaigns_by_list_name("Mailing List Name") campaigns = h.find_campaigns_by_list_id("Mailing List ID") campaigns = h.find_campaigns_by_type("regular") campaign = h.find_campaign_by_id("Campaign ID") campaign = h.find_campaign_by_title("Campaign Title")
To create a new campaign, use the create_campaign method:
new_campaign = h.create_campaign(...)
Take a look at Hominid::Campaign to see the methods that are available for interacting with your campaigns.
There are a series of helper methods that are also made available with the Hominid gem. For example, to retrieve information about the Mailchimp account associated with your API key, simply:
account_details_ = h.account_details
In this case, the account_details object can be accessed like:
account_details.contact.company account_details.orders
Take a look at Hominid::Helper to see the helper methods that are available.
There are a couple of security methods that are also made available with the Hominid gem. These are primarily used for dealing with API keys, and require your Mailchimp account username and password:
h.api_keys('username', 'password')
Take a look at Hominid::Security to see the security methods that are available.
Hominid is maintained by Brian Getting. A very special thank-you to Michael Strüder for all of his hard work. Also, Hominid wouldn’t be anywhere near as awesome as it is today without fantastic contributions and inspiration from:
-
Fork the project.
-
Make your feature addition or bug fix.
-
Add tests for it. This is important so I don’t break it in a future version unintentionally.
-
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-
Send me a pull request. Bonus points for topic branches.
Copyright © 2009 Brian Getting. See LICENSE for details.