Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Updated & maintained MailChimp API v1.3 wrapper for Python
Python
Branch: master
Pull request Compare This branch is 89 commits ahead, 7 commits behind Leftium:master.

Version bump

latest commit 5686b1178b
Mike Helmick authored
Failed to load latest commit information.
mailsnake Version bump
.gitignore additional ignores
LICENSE 1.5.0 release
MANIFEST.in 1.5.0 release
README.md Add OAuth token example to README
README.rst 1.6.0 release, update README
setup.py Version bump

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.