babney-hominid

h1. Hominid

Hominid is a Ruby gem that provides a wrapper for interacting with the "Mailchimp":http://www.mailchimp.com email marketing service API ("version 1.2":http://www.mailchimp.com/api/1.2/).

h2. Installation

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

Hominid is hosted at "Gemcutter":http://gemcutter.org. Be sure that you have the Gemcutter gem installed if you are having trouble installing Hominid:

sudo gem install gemcutter
gem tumble

h2. Configuration

You will need to create a "Mailchimp":http://www.mailchimp.com/signup 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.

h2. 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).

h3. Working with Lists

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

h4. 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)

h4. Subscribing

To subscribe a person or persons to a Mailchimp list:

list.subscribe("[e-mail]")

list.subscribe_many([{:EMAIL => '[e-mail]', :EMAIL_TYPE => 'html'}, {:EMAIL => '[e-mail]', :EMAIL_TYPE => 'html'}])

h4. Unsubscribing

To unsubscribe a person or persons from a Mailchimp list:

list.unsubscribe("[e-mail]")

list.unsubscribe_many(['[e-mail]', '[e-mail]'])

h4. 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('[e-mail]', {:EMAIL => '[e-mail]'}, '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@.

h3. Working with Campaigns

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

h4. 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")

h4. 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)

h4. 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)

h3. 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")

h2. 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":http://www.mailchimp.com/api/webhooks/.

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

h2. Contributors

Hominid is maintained by "Brian Getting":http://terra-firma-design.com. A very special thank-you to "Michael Strüder":http://github.com/mikezter 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:

• "Alan Harper":http://github.com/aussiegeek
• "Will":http://github.com/willinfront
• "Ben Woosley":http://github.com/Empact
• "banker":http://github.com/banker
• "Kristoffer Renholm":http://github.com/renholm
• "Wiktor Schmidt":http://github.com/netguru
• "ron":http://github.com/ron
• "Matthew Carlson":http://mandarinsoda.com/
• "Kelly Mahan":http://digimedia.com/
• "C.G. Brown":http://www.projectlocker.com/

h2. 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.

h2. Copyright

Copyright (c) 2009 Brian Getting. See LICENSE for details.