ak-postmonkey 1.0b1
Appknox fork of Python wrapper for Mailchimp API
License: FreeBSD
Keywords: mailchimp

PostMonkey 1.0b
===============

`PostMonkey` is a simple Python (2.6+) wrapper for MailChimp's API
version 1.3.


Features
========

1) 100% test coverage
2) Connection handling via the excellent `Requests <http://docs.python-requests.org>`_ library
3) Configurable timeout
4) Simple `Exceptions`


Installation
============

You can install postmonkey via `easy_install`:

.. code-block:: console

    easy_install postmonkey

Or by using `pip` (requires you to specify the version because latest is 1.0b):

.. code-block:: console

    pip install postmonkey==1.0b

Or by placing the requirement in `install_requires` in your `setup.py` file:

.. code-block:: python

      install_requires=[
          # all your other packages
          'postmonkey==1.0b',
      ]


Basic Usage
===========

Once you create a `PostMonkey` instance with your MailChimp API key,
you can use it to call MailChimp's API methods directly:

.. code-block:: python

    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
<http://apidocs.mailchimp.com/api/rtfm/>`_ 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 <http://apidocs.mailchimp.com/api/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
<http://apidocs.mailchimp.com/api/1.3/exceptions.field.php>`_ for additional
details.


Examples
========

Create a new `PostMonkey` instance with a 10 second timeout for requests:

.. code-block:: python

    from postmonkey import PostMonkey
    pm = PostMonkey('your_api_key', timeout=10)


Get the IDs for your campaign lists:

.. code-block:: python

    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:

.. code-block:: python

    pm.listSubscribe(id=5, email_address="emailaddress")


Catch an exception returned by MailChimp (invalid list ID):

.. code-block:: python

    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:

.. code-block:: python

    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']



=========
Changelog
=========

-Initial Release

-2012-10-11: Quote JSON string before sending POST request

-2013-07-03: Documentation updates and version bump (no code changes)