Hominid

Hominid is a Ruby gem that provides a wrapper for interacting with the Mailchimp email marketing service API (version 1.2).

Installation

sudo gem install hominid, :version => '>= 2.0.1', :source => "http://gemcutter.org"

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
gem tumble

Configuration

You will need to create a Mailchimp account and get your API key (available at http://admin.mailchimp.com/account/api/) in order to get started.

If you are using Hominid inside a Rails application, you can create a config file at /config/hominid.yml with your Mailchimp account information and basic configuration options:

development:
 username: USERNAME
 password: PASSWORD
 api_key: API KEY
 send_goodbye: false
 send_notify: false
 double_opt: false

...

Run rake hominid:config from within a Rails app to create an empty config file. Note: You will need to

require 'hominid'

in your Rakefile to make this rake task available to your application.

Usage

Not all API methods are supported (yet). Currently there are classes for working with lists (Hominid::List_), campaigns (Hominid::Campaign_) and accessing the helper methods (Hominid::Helper).

Working with Lists

The Hominid::List class is available for working finding lists and working with particular lists. See Hominid::List for more information.

List Finder Methods

There are finder methods for working with lists. Refer to Hominid::List to see the other finders availables.

lists = Hominid::List.all

list = Hominid::List.find_by_name("List Name")

list = Hominid::List.find(id_or_web_id)

Subscribing

To subscribe a person or persons to a Mailchimp list:

list.subscribe("[email protected]")

list.subscribe_many([{:EMAIL => '[email protected]', :EMAIL_TYPE => 'html'}, {:EMAIL => '[email protected]', :EMAIL_TYPE => 'html'}])

Unsubscribing

To unsubscribe a person or persons from a Mailchimp list:

list.unsubscribe("[email protected]")

list.unsubscribe_many(['[email protected]', '[email protected]'])

Updating

In the following example, we will be changing a person’s email address on the Mailchimp list from sample to another:

list.update_member('[email protected]', {:EMAIL => '[email protected]'}, 'html')

You can also updated other attributes by including the MERGE_VARS that you want to change, such as EMAIL, FNAME, LNAME and INTERESTS. Get a list of merge tags for a particular list by running list.merge_tags.

Working with Campaigns

The Hominid::Campaign class provides methods for working with a campaigns.

Campaign Finder Methods

There are finder methods for campaigns as well. Refer to Hominid::Campaign to see the other finders available.

campaigns = Hominid::Campaign.all

campaigns = Hominid::Campaign.find_by_list_name("List Name")

Creating a Campaign

You can create new campaigns using Hominid as well. Please refer to the documentation in Hominid::Base for more information about the options available when creating a new campaign.

new_campaign = Hominid::Campaign.create('regular', options, content, segment_opts, type_opts)

Schedule a Campaign

As an example of how to work with a particular campaign, use the Hominid::Campaign class. Extending from the previous example, since the #create_campaign method returns the ID of the created campaign, we can use it to instantiate the Hominid::Campaign class and schedule our new campaign to go be delivered 2 days from now:

campaign = Hominid::Campaign.new(:id => new_campaign)

campaign.schedule_campaign(2.days.from_now)

Helper Methods

The Hominid::Helper class provides a way to access the helper methods for the Mailchimp API. For example, to create a new folder for filing campaigns:

folder = Hominid::Helper.create_folder("Folder Name")

Syncing Your Application

If you are integrating an application with Mailchimp, Hominid will provide a way for your app to connect with your Mailchimp account. However, it does not provide a way for Mailchimp to connect to your application, which is why Mailchimp has implemented web hooks.

The Hominid::Webhook class helps with receiving POST data from a Mailchimp webhook:

hook = Hominid::Webhook.new(params)
case hook.event
when "subscribe"
  user = User.find_by_email(hook.email)
  user.opted_in = true
  user.save
when "unsubscribe"
  user = User.find_by_email(hook.email)
  user.opted_in = false
  user.save
when "profile"
  user = User.find_by_email(hook.email)
  user.first_name = hook.first_name
  user.last_name = hook.last_name
  user.email_type = hook.email_type
  user.save
when "upemail"
  user = User.find_by_email(hook.old_email)
  user.email = hook.new_email
  user.save
end

Contributors

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:

Note on Patches/Pull Requests

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.