Project description

python-mailchimp-api

A straighforward python client for v3 of MailChimp API using requests >=
2.7.0.

Getting Started

Installation

This client is hosted at PyPi under the name mailchimp3, to install
it, simply run

pip install mailchimp3

Upgrading from v2.x

The order of arguments for initializing the Mailchimp API has been
reversed starting in 2.1.0 as the username is an optional argument for
basic auth. Please reverse the order of your arguments or remove the
username argument entirely. The name of the authentication argument has
also changed from mc_secret to mc_api.

Upgrading from v1.x

The installation procedure for 2.x is the same as before, however there
are a massive number of changes to the naming conventions within this
wrapper and the way in which certain methods are called. Please read the
documentation below carefully for information on the new structure and
expanded functionality. With this release, all documented endpoints are
implemented and all endpoint methods are available.

OAuth Support

In addition to HTTP Basic Authentication, MailChimp supports
authentication through OAuth2. Information on obtaining the proper
access key can be found
here.

Pagination

Simply add count and offset arguments in your function. The
count is how many records to return, the offset is how many records to
skip. For endpoints that allow the pagination parameters, the all()
method has an additional boolean get_all argument that will loop
through all records until the API no longer returns any to get all
records without manually performing an additional query. By default,
count is 10 and offset is 0 for all endpoints that support it. The
get_all parameter on the all() method on any endpoint defaults to
false, which follows the values that are provided in the call, and using
get_all=True will ignore the provided count and offset to ensure
that all records are returned. When using get_all, the count will be
5000, to fetch large numbers of records without flooding the system with
requests. The large size of count should not impact calls which are
expected to return a very small number of records, and should improve
performance for calls where fetching 5000 records would only provide a
fraction by preventing the delay of making a huge number of requests.

client.lists.members.all('123456', count=100, offset=0)

Fields

Many endpoints allow you to select which fields will be returned out of
all available fields (for example, only the email_address of a member).
Simply add fields arguments in your function. The following only
display email_address and id for each member in list 123456:

API Endpoints

Below is the list of all endpoints and the methods that can be called
against them. Any endpoint that has a method that takes an ID argument
(for example the app_id in the authorized_apps endpoint or the
subscriber_hash in the list members endpoints) will record all IDs
passed as well as those generated by methods that will only ever return
a single result such as the create() method present on some endpoints.
These stored attributes are only available at the level that they were
passed or created at and must be passed again to interact with a lower
or higher level such as accessing a list and then a member. The below
code assumes that you have initialized the MailChimp class as listed
above with the name client.

Default Content

Logging

The MailChimp client will log request/response detail into the
mailchimp3.client logging namespace. Consider the following snippet to
get started with logging:

importloggingfh=logging.FileHandler('/path/to/some/log.log')logger=logging.getLogger('mailchimp3.client')logger.addHandler(fh)# use the client normallyclient.lists.all(**{'fields':'lists.date_created'})