PostMonkey is a simple Python (2.6+) wrapper for MailChimp’s API version 1.3.
Once you create a PostMonkey instance with your MailChimp API key, you can use it to call MailChimp’s API methods directly:
from postmonkey import PostMonkey
pm = PostMonkey('your_api_key')
pm.ping() # returns u"Everything's Chimpy!"
If the MailChimp method call accepts parameters, you can supply them in the form of keyword arguments. See Examples for common use cases, and refer to the MailChimp API v1.3 official documentation for a complete list of method calls, parameters, and response objects.
MailChimp has established guidelines/limits for API usage, so please refer to their FAQ for information.
Note: it is the caller’s responsibility to supply valid method names and any required parameters. If MailChimp receives an invalid request, PostMonkey will raise a postmonkey.exceptions.MailChimpException containing the error code and message. See MailChimp API v1.3 - Exceptions for additional details.
Create a new PostMonkey instance with a 10 second timeout for requests:
from postmonkey import PostMonkey
pm = PostMonkey('your_api_key', timeout=10)
Get the IDs for your campaign lists:
lists = pm.lists()
# print the ID and name of each list
for list in lists['data']:
print list['id'], list['name']
Subscribe “emailaddress” to list ID 5:
pm.listSubscribe(id=5, email_address="emailaddress")
Catch an exception returned by MailChimp (invalid list ID):
from postmonkey import MailChimpException
try:
pm.listSubscribe(id=42, email_address="emailaddress")
except MailChimpException, e:
print e.code # 200
print e.error # u'Invalid MailChimp List ID: 42'
Get campaign data for all “sent” campaigns:
campaigns = pm.campaigns(filters=[{'status': 'sent'}])
# print the name and count of emails sent for each campaign
for c in campaigns['data']:
print c['title'], c['emails_sent']
apikey
The API key for your MailChimp account, obtained from MailChimp.
endpoint
The URL used for API calls. Will be inferred from your API key unless you specifically override it (not recommended except for testing).
datacenter
The MailChimp supplied data center for your account. Will be inferred from your API key unless you specifically override it. Cannot be accessed or modified after initialization.
params
Any extra keyword arguments supplied on initialization will be made available in a dict via this attribute. Only include parameters that should be used on each and every API call. For instance, if you want to add a subscription form to your website, you can parameterize the list’s ID.
postrequest
Defaults to requests.post, and should not be changed except for testing or if you have a really good reason. If you do override it, you must supply a function that takes a URL, a JSON encoded payload, a dict of HTTP headers, and optionally a timeout (in seconds). Must return a response object with a text attribute containing valid JSON.
Factory method that takes a dict, finds keys prefixed with ‘postmonkey.’, and uses them to create a new PostMonkey instance. Intended for use with console scripts or web frameworks that load config file data into a dict.
Raised if MailChimp responds with anything other than valid JSON. PostMonkey uses MailChimp’s JSON API exclusively so it is unlikely that this will be raised. The response that caused the error is made available via the obj attribute.
If MailChimp returns an exception code as part of their response, this exception will be raised. Contains the unmodified code (int) and error (unicode) attributes returned by MailChimp.
If any exception is made during the POST request to MailChimp’s server, PostRequestError will be raised. It wraps the underlying exception object and makes it available via the exc attribute.
Raised if a method call contains parameters that cannot be serialized to JSON. The object that caused the error is made available via the obj attribute.