Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Updated & maintained MailChimp API v1.3 wrapper for Python

branch: master

This branch is 0 commits ahead and 0 commits behind master

Update setup.py

Version bump
latest commit 544b916c82
Mike Helmick authored
Octocat-spinner-32 mailsnake Option to supply datacenter explicitly February 11, 2013
Octocat-spinner-32 .gitignore additional ignores June 06, 2012
Octocat-spinner-32 LICENSE 1.5.0 release June 14, 2012
Octocat-spinner-32 MANIFEST.in 1.5.0 release June 14, 2012
Octocat-spinner-32 README.md Add OAuth token example to README February 11, 2013
Octocat-spinner-32 README.rst 1.6.0 release, update README July 13, 2012
Octocat-spinner-32 setup.py Update setup.py February 11, 2013
README.md

MailSnake

MailSnake is a Python wrapper for MailChimp's The API, STS API, Export API, and the new Mandrill API. (Now with support for Python 3)

Installation

pip install mailsnake

Usage

from mailsnake import MailSnake
from mailsnake.exceptions import *

ms = MailSnake('YOUR MAILCHIMP API KEY')
try:
    ms.ping() # returns "Everything's Chimpy!"
except MailSnakeException:
    print 'An error occurred. :('

You can also catch specific errors:

ms = MailSnake('my_wrong_mailchimp_api_key_that_does_not_exist')
try:
    ms.ping() # returns "Everything's Chimpy!"
except InvalidApiKeyException:
    print 'You have a bad API key, sorry.'

The default API is MCAPI, but STS, Export, and Mandrill can be used by supplying an api argument set to 'sts', 'export', or 'mandrill' respectively. Here's an example:

mcsts = MailSnake('YOUR MAILCHIMP API KEY', api='sts')
mcsts.GetSendQuota() # returns something like {'Max24HourSend': '10000.0', 'SentLast24Hours': '0.0', 'MaxSendRate': '5.0'}

Since the Mandrill API is divided into sections, one must take that into account when using it. Here's an example:

mapi = MailSnake('YOUR MANDRILL API KEY', api='mandrill')
mapi.users.ping() # returns 'PONG!'

or:

mapi_users = MailSnake('YOUR MANDRILL API KEY', api='mandrill', api_section='users')
mapi_users.ping() # returns 'PONG!'

Some Mandrill functions have a dash(-) in the name. Since Python function names can't have dashes in them, use underscores(_) instead:

mapi = MailSnake('YOUR MANDRILL API KEY', api='mandrill')
mapi.messages.send(message={'html':'email html', 'subject':'email subject', 'from_email':'from@example.com', 'from_name':'From Name', 'to':[{'email':'to@example.com', 'name':'To Name'}]}) # returns 'PONG!'

OAuth Tokens

You can use a MailChimp OAuth token in place of an API key, but because MailChimp's tokens don't include the datacenter as a suffix, you must supply it yourself (substitute an actual number for X below):

ms = MailSnake('A MAILCHIMP OAUTH TOKEN', dc='usX')
ms.ping() # returns "Everything's Chimpy!" just like with an API key

If you completed the OAuth dance as described in the MailChimp OAuth2 documentation, you should have discovered the datacenter associated with the token when making the metadata request.

Additional Request Options

MailSnake uses Requests for HTTP. If you require more control over how your request is made, you may supply a dictionary as the value of requests_opts when constructing an instance of MailSnake. This will be passed through (as kwargs) to requests.post(). See the next section for an example.

Streamed Responses

Since responses from the MailChimp Export API can be quite large, it is helpful to be able to consume them in a streamed fashion. If you supply requests_opts={'stream': True} when calling MailSnake, a generator is returned that deserializes and yields each line of the streamed response as it arrives:

from mailsnake import MailSnake

opts = {'stream': True}
export = MailSnake('YOURAPIKEY', api='export', requests_opts=opts)
resp = export.list(id='YOURLISTID')

lines = 0
for list_member in resp():
    if lines > 0: # skip header row
        print list_member
    lines += 1

If you are using Requests < 1.0.0, supply {'prefetch': False} instead of {'stream': True}.

Note

API parameters must be passed by name. For example:

mcapi.listMemberInfo(id='YOUR LIST ID', email_address='name@example.com')

API Documentation

Note that in order to use the STS API or Mandrill you first need to enable the Amazon Simple Email Service or the Mandrill integration in MailChimp.

MailChimp API v1.3 documentation

MailChimp STS API v1.0 documentation

MailChimp Export API v1.0 documentation

Something went wrong with that request. Please try again.