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.
For example, to fetch your first 100 campaigns (page 0):
campaigns = gb.campaigns({:start => 0, :limit => 100})
Similarly, to fetch your first 100 lists:
lists = gb.lists({:start => 0, :limit=> 100})
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})
Gibbon defaults to a 30 second timeout. You can optionally set your own timeout (in seconds) like so:
gb.timeout = 5
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.
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.
##Thanks
- Justin Ip
- elshimone
- jlxw
- Jon McCartie
- Calvin Yu
- Dave Worth
- Mike Skalnik
- Kristopher Murata
- Michael Klishin
- Rails for camelize gsub
##Copyrights
- Copyright (c) 2010 Amro Mousa. See LICENSE.txt for details.
- MailChimp (c) 2001-2010 The Rocket Science Group.