python-mailchimp

The MailChimp API client uses a hierarchical structure where IDs must be passed explicitly to navigate between levels.

Key Principles:

1. ID Persistence: When a method returns a single result (like create()) or takes an ID argument (like app_id or subscriber_hash), the client tracks these IDs.
2. Scope of IDs: Stored attributes (IDs) are only available at the specific level they were passed or created.
3. Manual Navigation: To move between levels (e.g., from a List to a Member, or from a Store to an Order), you must explicitly pass the parent IDs again.

Example Pattern: To access a specific member within a list, you cannot simply call client.members.get(). You must provide the context: client.lists.members.get(list_id='...', subscriber_hash='...').

The MailChimp API is organized into a hierarchical structure of endpoints. Many methods require specific IDs (e.g., app_id, workflow_id, list_id, or subscriber_hash) to target specific resources.

Important Scoping Rule: Stored attributes like IDs are only available at the specific level they were passed or created. To move between levels (e.g., from a List to a specific Member), you must pass the parent ID again. For example, to access a member, you must provide both the list_id and the subscriber_hash.

For endpoints that support pagination, use the following arguments:

• count: The number of records to return (defaults to 10).
• offset: The number of records to skip (defaults to 0).
• get_all: A boolean argument available on the .all() method. When set to True, the client will loop through all records automatically. When get_all=True, the count defaults to 500 and the provided offset is ignored.

It is recommended to use a larger count when fetching many records to improve performance and avoid flooding the system with small requests.

# Example: Fetch 100 members starting from offset 0
client.lists.members.all('123456', count=100, offset=0)

The all() method on supported endpoints includes a get_all boolean argument. When get_all=True:

• The client loops through all records automatically until the API returns no more.
• It ignores the provided offset to ensure a complete fetch.
• The count defaults to 500 (unless otherwise specified) to improve performance and avoid flooding the system with small requests.

# Fetches every member in the list regardless of offset
client.lists.members.all('123456', get_all=True)

The MailChimp client logs request and response details using the mailchimp3.client logging namespace. To capture these details, configure a logger for mailchimp3.client and attach a handler (such as a FileHandler). This is useful for debugging API interactions and inspecting the raw JSON payloads returned by MailChimp.

import logging

# Configure logging to a file
fh = logging.FileHandler('/path/to/some/log.log')
logger = logging.getLogger('mailchimp3.client')
logger.addHandler(fh)

# Use the client normally; requests/responses will be logged to the file
client.lists.all(**{'fields': 'lists.date_created'})

The mailchimp3 client is hosted on PyPi. Install it using the following command:

pip install mailchimp3

Starting in version 2.1.0, the order of arguments for initializing the MailChimp class was reversed because the username is optional. Additionally, the authentication parameter name changed from mc_secret to mc_api.

Action required: Reverse the order of your arguments or remove the username argument entirely, and use mc_api instead of mc_secret.

The MailChimp client logs request and response details to the mailchimp3.client logging namespace. To capture these details (such as the full URL and JSON response body) into a file, configure a logger for that specific namespace using Python's logging module.

import logging

# Setup a file handler to capture request/response details
fh = logging.FileHandler('/path/to/some/log.log')
logger = logging.getLogger('mailchimp3.client')
logger.addHandler(fh)

# Use the client normally
# The logs will now include details like:
# GET Request: https://us15.api.mailchimp.com/3.0/lists?fields=lists.date_created
# GET Response: 200 {"lists": [...]}