python-mailchimp-api
A straightforward 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.
History
Up to date with changelog features listed through 3/03/2017.
Initialization
Grab YOUR_API_KEY from your mailchimp account (Account > Extra > Api
Keys). YOUR_USERNAME is the one you use to log in on the website and
is optional.
from mailchimp3 import MailChimp
client = MailChimp(mc_api='YOUR_API_KEY', mc_user='YOUR_USERNAME')
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 offset to ensure that all records are returned. When using
get_all, the count will be 500 unless otherwise specified. It is strongly
recommended to avoid small values for count to fetch large numbers of records
because this will flood the system. A large count size should not impact calls
which are expected to return a very small number of records, and should improve
performance for calls where fetching 500 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:
client.lists.members.all('123456', get_all=True, fields="members.email_address,members.id")
Examples
# returns all the lists (only name and id)
client.lists.all(get_all=True, fields="lists.name,lists.id")
# returns all members inside list '123456'
client.lists.members.all('123456', get_all=True)
# return the first 100 member's email addresses for the list with id 123456
client.lists.members.all('123456', count=100, offset=0, fields="members.email_address")
# returns the list matching id '123456'
client.lists.get('123456')
# add John Doe with email [email protected] to list matching id '123456'
client.lists.members.create('123456', {
'email_address': '[email protected]',
'status': 'subscribed',
'merge_fields': {
'FNAME': 'John',
'LNAME': 'Doe',
},
})
# returns all the campaigns
client.campaigns.all(get_all=True)
# You can also disable at runtime with the optional ``enabled`` parameter.
# Every API call will return None
client = MailChimp('YOUR SECRET KEY', enabled=False)
# You are encouraged to specify a value in seconds for the ``timeout``
# parameter to avoid hanging requests.
client = MailChimp('YOUR SECRET KEY', timeout=10.0)
# You are encouraged to specify a User-Agent for requests to the MailChimp
# API. Headers can be specified using the ``request_headers`` parameter.
headers = requests.utils.default_headers()
headers['User-Agent'] = 'Example ([email protected])'
client = MailChimp('YOUR SECRET KEY', request_headers=headers)
API Structure
All endpoints follow the structure listed in the official MailChimp API v3 documentation. The structure will be listed below and then the individual methods available after.
MailChimp
+- Root
+- Authorized Apps
+- Automations
| +- Actions
| +- Emails
| | +- Actions
| | +- Queues
| +- Removed Subscribers
+- Batch Operations
+- Batch Webhooks
+- Campaign Folders
+- Campaigns
| +- Actions
| +- Content
| +- Feedback
| +- Send Checklist
+- Conversations
| +- Messages
+- Customer Journeys
+- Stores
| +- Carts
| | +- Lines
| +- Customers
| +- Orders
| | +- Lines
| +- Products
| +- Images
| +- Variants
| +- Promo Rules
| +- Promo Codes
+- File Manager Files
+- File Manager Folders
+- Landing Pages
| +- Actions
| +- Content
+- Lists
| +- Abuse Reports
| +- Activity
| +- Clients
| +- Growth History
| +- Interest Categories
| | +- Interests
| +- Members
| | +- Activity
| | +- Events
| | +- Goals
| | +- Notes
| | +- Tags
| +- Merge Fields
| +- Segments
| | +- Segment Members
| +- Signup Forms
| +- Twitter Lead Generation Carts
| +- Webhooks
+- Ping
+- Reports
| +- Campaign Abuse
| +- Campaign Advice
| +- Campaign Open reports
| +- Click Reports
| | +- Members
| +- Domain Performance
| +- EepURL Reports
| +- Email Activity
| +- Google Analytics
| +- Location
| +- Sent To
| +- Sub-Reports
| +- Unsubscribes
+- Search Campaigns
+- Search Members
+- Template Folders
+- Templates
+- Default Content
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.
Root
Root
client.root.get()
Authorized Apps
Authorized Apps
client.authorized_apps.create(data={})
client.authorized_apps.all(get_all=False)
client.authorized_apps.get(app_id='')
Automations
Automations
client.automations.all(get_all=False)
client.automations.get(workflow_id='')
Automation Actions
client.automations.actions.pause(workflow_id='')
client.automations.actions.start(workflow_id='')
Automation Emails
client.automations.emails.all(workflow_id='')
client.automations.emails.get(workflow_id='', email_id='')
Automation Email Actions
client.automations.emails.actions.pause(workflow_id='', email_id='')
client.automations.emails.actions.start(workflow_id='', email_id='')
Automation Email Queues
client.automations.emails.queues.create(workflow_id='', email_id='', data={})
client.automations.emails.queues.all(workflow_id='', email_id='')
client.automations.emails.queues.get(workflow_id='', email_id='', subscriber_hash='')
Automation Removed Subscribers
client.automations.removed_subscribers.create(workflow_id='', data={})
client.automations.removed_subscribers.all(workflow_id='')
Batch Operations
Batch Operations
client.batch_operations.create(data={})
client.batch_operations.all(get_all=False)
client.batch_operations.get(batch_id='')
client.batch_operations.delete(batch_id='')
Batch Webhooks
Batch Webhooks
client.batch_webhooks.create(data={})
client.batch_webhooks.all(get_all=False)
client.batch_webhooks.get(batch_webhook_id='')
client.batch_webhooks.update(batch_webhook_id='', data={})
client.batch_webhooks.delete(batch_webhook_id='')
Campaigns
Folders
client.campaign_folders.create(data={})
client.campaign_folders.all(get_all=False)
client.campaign_folders.get(folder_id='')
client.campaign_folders.update(folder_id='', data={})
client.campaign_folders.delete(folder_id='')
Campaigns
client.campaigns.create(data={})
client.campaigns.all(get_all=False)
client.campaigns.get(campaign_id='')
client.campaigns.update(campaign_id='')
client.campaigns.delete(campaign_id='')
Campaign Actions
client.campaigns.actions.cancel(campaign_id='')
client.campaigns.actions.pause(campaign_id='')
client.campaigns.actions.replicate(campaign_id='')
client.campaigns.actions.resume(campaign_id='')
client.campaigns.actions.schedule(campaign_id='', data={})
client.campaigns.actions.send(campaign_id='')
client.campaigns.actions.resend(campaign_id='')
client.campaigns.actions.test(campaign_id='', data={})
client.campaigns.actions.unschedule(campaign_id='')
Campaign Content
client.campaigns.content.get(campaign_id='')
client.campaigns.content.update(campaign_id='', data={})
Campaign Feedback
client.campaigns.feedback.create(campaign_id='', data={})
client.campaigns.feedback.all(campaign_id='', get_all=False)
client.campaigns.feedback.get(campaign_id='', feedback_id='')
client.campaigns.feedback.update(campaign_id='', feedback_id='', data={})
client.campaigns.feedback.delete(campaign_id='', feedback_id='')
Campaign Send Checklist
client.campaigns.send_checklist.get(campaign_id='')
Conversations
Conversations
client.conversations.all(get_all=False)
client.conversations.get(conversation_id='')
Conversation Messages
client.conversations.messages.create(conversation_id='', data={})
client.conversations.messages.all(conversation_id='')
client.conversations.messages.get(conversation_id='', message_id='')
Customer Journeys
Customer Journeys
client.customer_journeys.trigger(journey_id='', step_id='', data={})
E-Commerce
Stores
client.stores.create(data={})
client.stores.all(get_all=False)
client.stores.get(store_id='')
client.stores.update(store_id='', data={})
client.stores.delete(store_id='')
Store Carts
client.stores.carts.create(store_id='', data={})
client.stores.carts.all(store_id='', get_all=False)
client.stores.carts.get(store_id='', cart_id='')
client.stores.carts.update(store_id='', cart_id='', data={})
client.stores.carts.delete(store_id='', cart_id='')
Store Cart Lines
client.stores.carts.lines.create(store_id='', cart_id='', data={})
client.stores.carts.lines.all(store_id='', cart_id='', get_all=False)
client.stores.carts.lines.get(store_id='', cart_id='', line_id='')
client.stores.carts.lines.update(store_id='', cart_id='', line_id='', data={})
client.stores.carts.lines.delete(store_id='', cart_id='', line_id='')
Store Customers
client.stores.customers.create(store_id='', data={})
client.stores.customers.all(store_id='', get_all=False)
client.stores.customers.get(store_id='', customer_id='')
client.stores.customers.update(store_id='', customer_id='', data={})
client.stores.customers.create_or_update(store_id='', customer_id='', data={})
client.stores.customers.delete(store_id='', customer_id='')
Store Orders
client.stores.orders.create(store_id='', data={})
client.stores.orders.all(store_id='', get_all=False)
client.stores.orders.get(store_id='', order_id='')
client.stores.orders.update(store_id='', order_id='', data={})
client.stores.orders.delete(store_id='', order_id='')
Store Order Lines
client.stores.orders.lines.create(store_id='', order_id='', data={})
client.stores.orders.lines.all(store_id='', order_id='', get_all=False)
client.stores.orders.lines.get(store_id='', order_id='', line_id='')
client.stores.orders.lines.update(store_id='', order_id='', line_id='', data={})
client.stores.orders.lines.delete(store_id='', order_id='', line_id='')
Store Products
client.stores.products.create(store_id='', data={})
client.stores.products.all(store_id='', get_all=False)
client.stores.products.get(store_id='', product_id='')
client.stores.products.update(store_id='', product_id='')
client.stores.products.delete(store_id='', product_id='')
Store Product Images
client.stores.products.images.create(store_id='', product_id='', data={})
client.stores.products.images.all(store_id='', product_id='', get_all=False)
client.stores.products.images.get(store_id='', product_id='', image_id='')
client.stores.products.images.update(store_id='', product_id='', image_id='', data={})
client.stores.products.images.delete(store_id='', product_id='', image_id='')
Store Product Variants
client.stores.products.variants.create(store_id='', product_id='', data={})
client.stores.products.variants.all(store_id='', product_id='', get_all=False)
client.stores.products.variants.get(store_id='', product_id='', variant_id='')
client.stores.products.variants.update(store_id='', product_id='', variant_id='', data={})
client.stores.products.variants.create_or_update(store_id='', product_id='', variant_id='', data={})
client.stores.products.variants.delete(store_id='', product_id='', variant_id='')
File Manager
Files
client.files.create(data={})
client.files.all(get_all=False)
client.files.get(file_id='')
client.files.update(file_id='', data={})
client.files.delete(file_id='')
Folders
client.folders.create(data={})
client.folders.all(get_all=False)
client.folders.get(folder_id='')
client.folders.update(folder_id='', data={})
client.folders.delete(folder_id='')
Landing Pages
Landing Pages
client.landing_pages.create(data={})
client.landing_pages.all()
client.landing_pages.all(fields='')
client.landing_pages.get(page_id='')
client.landing_pages.update(page_id='', data={})
client.landing_pages.delete(page_id='')
Landing Pages Actions
client.landing_pages.actions.publish(page_id='')
client.landing_pages.actions.unpublish(page_id='')
Landing Pages Content
client.landing_pages.content.get(page_id='')
Lists
Lists
client.lists.create(data={})
client.lists.update_members(list_id='', data={})
client.lists.all(get_all=False)
client.lists.get(list_id='')
client.lists.update(list_id='', data={})
client.lists.delete(list_id='')
List Abuse Reports
client.lists.abuse_reports.all(list_id='', get_all=False)
client.lists.abuse_reports.get(list_id='', report_id='')
List Activity
client.lists.activity.all(list_id='', subscriber_hash='')
client.lists.activity.feed(list_id='', subscriber_hash='')
List Clients
client.lists.clients.all(list_id='')
List Growth History
client.lists.growth_history.all(list_id='', get_all=False)
client.lists.growth_history.get(list_id='', month='')
List Interest Categories
client.lists.interest_categories.create(list_id='', data={})
client.lists.interest_categories.all(list_id='', get_all=False)
client.lists.interest_categories.get(list_id='', category_id='')
client.lists.interest_categories.update(list_id='', category_id='', data={})
client.lists.interest_categories.delete(list_id='', category_id='')
List Interest Category Interests
client.lists.interest_categories.interests.create(list_id='', category_id='', data={})
client.lists.interest_categories.interests.all(list_id='', category_id='', get_all=False)
client.lists.interest_categories.interests.get(list_id='', category_id='', interest_id='')
client.lists.interest_categories.interests.update(list_id='', category_id='', interest_id='', data={})
client.lists.interest_categories.interests.delete(list_id='', category_id='', interest_id='')
List Members
client.lists.members.create(list_id='', data={})
client.lists.members.all(list_id='', get_all=False)
client.lists.members.get(list_id='', subscriber_hash='')
client.lists.members.update(list_id='', subscriber_hash='', data={})
client.lists.members.create_or_update(list_id='', subscriber_hash='', data={})
client.lists.members.delete(list_id='', subscriber_hash='')
client.lists.members.delete_permanent(list_id='', subscriber_hash='')
List Member Activity
client.lists.members.activity.all(list_id='', subscriber_hash='')
List Member Events
client.lists.members.events.create(list_id='', subscriber_hash='', data={})
client.lists.members.events.all(list_id='', subscriber_hash='', get_all=False)
List Member Goals
client.lists.members.goals.all(list_id='', subscriber_hash='')
List Member Notes
client.lists.members.notes.create(list_id='', subscriber_hash='', data={})
client.lists.members.notes.all(list_id='', subscriber_hash='', get_all=False)
client.lists.members.notes.get(list_id='', subscriber_hash='', note_id='')
client.lists.members.notes.update(list_id='', subscriber_hash='', note_id='', data={})
client.lists.members.notes.delete(list_id='', subscriber_hash='', note_id='')
List Member Tags
client.lists.members.tags.update(list_id='', subscriber_hash='', data={})
client.lists.members.tags.all(list_id='', subscriber_hash='')
List Merge Fields
client.lists.merge_fields.create(list_id='', data={})
client.lists.merge_fields.all(list_id='', get_all=False)
client.lists.merge_fields.get(list_id='', merge_id='')
client.lists.merge_fields.update(list_id='', merge_id='', data={})
client.lists.merge_fields.delete(list_id='', merge_id='')
List Segments
client.lists.segments.create(list_id='', data={})
client.lists.segments.all(list_id='', get_all=False)
client.lists.segments.get(list_id='', segment_id='')
client.lists.segments.update(list_id='', segment_id='', data={})
client.lists.segments.update_members(list_id='', segment_id='', data={})
client.lists.segments.delete(list_id='', segment_id='')
List Segment Members
client.lists.segments.members.create(list_id='', segment_id='', data={})
client.lists.segments.members.all(list_id='', segment_id='', get_all=False)
client.lists.segments.members.delete(list_id='', segment_id='', subscriber_hash='')
List Signup Forms
client.lists.signup_forms.create(list_id='', data={})
client.lists.signup_forms.all(list_id='')
List Webhooks
client.lists.webhooks.create(list_id='', data={})
client.lists.webhooks.all(list_id='')
client.lists.webhooks.get(list_id='', webhook_id='')
client.lists.webhooks.update(list_id='', webhook_id='', data={})
client.lists.webhooks.delete(list_id='', webhook_id='')
Reports
Reports
client.reports.all(get_all=False)
client.reports.get(campaign_id='')
Campaign Abuse Reports
client.reports.abuse_reports.all(campaign_id='')
client.reports.abuse_reports.get(campaign_id='', report_id='')
Campaign Advice
client.reports.advice.all(campaign_id='')
Click Details Report
client.reports.click_details.all(campaign_id='', get_all=False)
client.reports.click_details.get(campaign_id='', link_id='')
Click Details Report Members
client.reports.click_details.members.all(campaign_id='', link_id='', get_all=False)
client.reports.click_details.members.get(campaign_id='', link_id='', subscriber_hash='')
Domain Performance Reports
client.reports.domain_performance.all(campaign_id='')
EepURL Reports
client.reports.eepurl.all(camnpaign_id='')
Email Activity Reports
client.reports.email_activity.all(campaign_id='', get_all=False)
client.reports.email_activity.get(campaign_id='', subscriber_hash='')
Locations Report
client.reports.locations.all(campaign_id='', get_all=False)
Sent To Reports
client.reports.sent_to.all(campaign_id='', get_all=False)
client.reports.sent_to.get(campaign_id='', subscriber_hash='')
Sub-Reports
client.reports.subreports.all(campaign_id='')
Unsubscribes
client.reports.unsubscribes.all(campaign_id='', get_all=False)
client.reports.unsubscribes.get(campaign_id='', subscriber_hash='')
Search
Campaigns
client.search_campaigns.get()
Members
client.search_members.get()
Templates
Folders
client.template_folders.create(data={})
client.template_folders.all(get_all=False)
client.template_folders.get(folder_id='')
client.template_folders.update(folder_id='', data={})
client.template_folders.delete(folder_id='')
Templates
client.templates.create(data={})
client.templates.all(get_all=False)
client.templates.get(template_id='')
client.templates.update(template_id='', data={})
client.templates.delete(template_id='')
Default Content
client.templates.default_content.all(template_id='')
Logging
The MailChimp client will log request/response detail into the mailchimp3.client logging namespace. Consider the following snippet to get started with logging:
import logging
fh = logging.FileHandler('/path/to/some/log.log')
logger = logging.getLogger('mailchimp3.client')
logger.addHandler(fh)
# use the client normally
client.lists.all(**{'fields': 'lists.date_created'})request/response detail will be appended into /path/to/some/log.log:
GET Request: https://us15.api.mailchimp.com/3.0/lists?fields=lists.date_created
GET Response: 200 {"lists":[{"date_created":"2017-05-10T13:53:05+00:00"},{"date_created":"2017-08-22T20:27:56+00:00"},{"date_created":"2017-05-12T21:22:15+00:00"},{"date_created":"2017-04-27T17:42:04+00:00"},{"date_created":"2017-05-10T14:14:49+00:00"},{"date_created":"2017-05-10T13:52:37+00:00"},{"date_created":"2017-05-10T13:51:40+00:00"}]}
Check the docs for more detail on the Python logging package.
Support
If you are having issues, please let us know or submit a pull request.
License
The project is licensed under the MIT License.