gibbon

Gibbon is a simple API wrapper for interacting with MailChimp API 1.3.

##Installation

$ gem install gibbon

##Requirements

A MailChimp account and API key. You can see your API keys here.

##Usage

There are a few ways to use Gibbon:

You can create an instance of the API wrapper:

gb = Gibbon.new("your_api_key")

You can set your api_key globally and call class methods:

Gibbon.api_key = "your_api_key"
Gibbon.lists

You can also set the environment variable 'MC_API_KEY' and Gibbon will use it when you create an instance:

u = Gibbon.new

Fetching data is as simple as calling API methods directly on the wrapper object. The API calls may be made with either camelcase or underscore separated formatting as you see in the "More Advanced Examples" section below.

Check the API documentation for details.

Fetching Campaigns

For example, to fetch your first 100 campaigns (page 0):

campaigns = gb.campaigns({:start => 0, :limit => 100})

Fetching Lists

Similarly, to fetch your first 100 lists:

lists = gb.lists({:start => 0, :limit=> 100})

More Advanced Examples

Getting batch member information for subscribers looks like this:

info = gb.list_member_info({:id => list_id, :email_address => email_array})

or

info = gb.listMemberInfo({:id => list_id, :email_address => email_array})

Fetch open and click detail for recipients of a particular campaign:

email_stats = gb.campaign_email_stats_aim({:cid => campaign_id, :email_address => email_array})

or

email_stats = gb.campaignEmailStatsAIM({:cid => campaign_id, :email_address => email_array})

Other Stuff

Gibbon defaults to a 30 second timeout. You can optionally set your own timeout (in seconds) like so:

gb.timeout = 5

Export API usage

In addition to the standard API you can make calls to the MailChimp Export API using a GibbonExport object. Given an existing Gibbon object you can request a new GibbonExporter object:

g = Gibbon.new(@api_key)
gibbon_export = g.get_exporter

or you can construct a new object directly:

gibbon_export = GibbonExport.new(@api_key)

Calling Export API functions is identical to making standard API calls but the return value is an Enumerator which loops over the lines returned from the Export API. This is because the data returned from the Export API is a stream of JSON objects rather than a single JSON array.

Error handling

By default you are expected to handle errors returned by the APIs manually. The APIs will return a Hash with two keys "errors", a string containing some textual information about the error, and "code", the numeric code of the error.

If you set the throws_exceptions boolean attribute for a given instance then Gibbon will attempt to intercept the errors and raise an exception.

Notes

As of 0.1.6, gibbon uses ActiveSupport::JSON.decode(). This means code that checked for weird API responses (like "true" on a successful call to "listSubscribe" or similar) will need to be tweaked to handle the boolean JSON.decode() returns as opposed to the string the MailChimp API returns. I understand the extra dependency might be a pain for some.

##Thanks

• Justin Ip
• elshimone
• jlxw
• Jon McCartie
• Calvin Yu
• Dave Worth
• Mike Skalnik
• Kristopher Murata
• Rails for camelize gsub

##Copyrights

• Copyright (c) 2010 Amro Mousa. See LICENSE.txt for details.
• MailChimp (c) 2001-2010 The Rocket Science Group.