Gibbon is a simple API wrapper for interacting with MailChimp API version 1.3.
Pull request Compare This branch is 1 commit ahead, 362 commits behind amro:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



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

Build Status


$ gem install gibbon


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


There are a few ways to use Gibbon:

You can create an instance of the API wrapper:

gb ="your_api_key")

You can set your api_key globally and call class methods:

Gibbon.api_key = "your_api_key"

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

u =

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.

Datacenter Aware

OAuth 2 Strategy provides you with tokens along with datacenter information e.g. us1, us2

gb ="your_api_key")
gb.datacenter = "us1"

This will automatically append "us1" to your key when using internally. Alternatively you can also do:

gb ="your_api_key-datacenter")

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})


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})


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_export = g.get_exporter

or you can construct a new object directly:

gibbon_export =

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.



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