Install & Compatibility
Where this runs
tested against v3.0.80 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.450s · 24.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.426s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import mailchimp_marketing as MailchimpMarketing
client = MailchimpMarketing.Client()
✗ from mailchimp_marketing import Client
client = Client()
The common convention shown in official examples is to import the package as 'MailchimpMarketing' and access 'Client' from there, or use explicit 'from mailchimp_marketing.client import Client' to avoid ambiguity if other modules define a 'Client' class. The former is more prevalent in documentation.
ApiClient.ApiException
✓ from mailchimp_marketing.api_client import ApiClient
try: ... except ApiClient.ApiException as e: ...
This quickstart demonstrates how to initialize the Mailchimp client using API key and server prefix from environment variables and perform a basic API call (ping). It also includes a commented-out example for listing audiences. Ensure `MAILCHIMP_API_KEY` and `MAILCHIMP_SERVER_PREFIX` are set in your environment.
import os
import mailchimp_marketing as MailchimpMarketing
from mailchimp_marketing.api_client import ApiClient
# It's recommended to store your API key and server prefix as environment variables.
# The server prefix (e.g., 'us1', 'us19') is typically the last part of your API key (e.g., 'YOUR_KEY-us19').
api_key = os.environ.get("MAILCHIMP_API_KEY", "")
server_prefix = os.environ.get("MAILCHIMP_SERVER_PREFIX", "")
# Fallback to extract server prefix from API key if not explicitly set
if not server_prefix and '-' in api_key:
server_prefix = api_key.split('-')[-1]
if not api_key:
print("ERROR: MAILCHIMP_API_KEY environment variable not set.")
print("Please set it to your Mailchimp API key. Example: export MAILCHIMP_API_KEY='yourkey-us1'")
exit(1)
if not server_prefix:
print("ERROR: MAILCHIMP_SERVER_PREFIX environment variable not set and could not be extracted from API key.")
print("Please set it to your Mailchimp server prefix (e.g., 'us1').")
exit(1)
# Initialize the Mailchimp Marketing Client
client = MailchimpMarketing.Client()
client.set_config({
"api_key": api_key,
"server": server_prefix
})
try:
# Example: Get basic account information (ping the API)
response = client.ping.get()
print("Successfully connected to Mailchimp API. Health status:")
print(response)
# Example: List all audiences (uncomment to run)
# print("\nFetching audiences...")
# audiences_response = client.lists.get_all_lists()
# if 'lists' in audiences_response:
# for list_item in audiences_response['lists']:
# print(f" - Name: {list_item.get('name')}, ID: {list_item.get('id')}")
# else:
# print("No audiences found or unexpected response.")
except ApiClient.ApiException as e:
print(f"Error calling Mailchimp API: {e}")
print(f"Status: {e.status}, Reason: {e.reason}, Body: {e.body}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaMailchimp billing is based on the total number of contacts across *all* audiences in your account. Using multiple audiences for segmentation can lead to duplicate contacts, increased costs, and management complexity. It's generally recommended to use a single master audience with tags and groups for segmentation instead.fixConsolidate contacts into a single audience and use Mailchimp's built-in tags and groups for effective segmentation. Regularly clean your list to remove inactive or unsubscribed contacts.
affects: All versions
breakingAs of June 1, 2025, Mailchimp has discontinued the 'Classic Automation Builder' and removed email automation features entirely from its Free plan. Users on the Free plan who relied on automations (e.g., welcome sequences) will need to upgrade to a paid plan or switch to an alternative service.fixIf your workflows depend on email automation, evaluate Mailchimp's paid plans or consider migrating to an email marketing platform that offers automation features within your budget.
affects: Free plan users as of June 1, 2025
gotchaAll Mailchimp API requests require both an API key and a server prefix (e.g., 'us1', 'us19'). The server prefix is often embedded in your API key (e.g., 'YOUR_KEY-us19'). Incorrectly providing or omitting the server prefix will result in authentication failures.fixEnsure both `api_key` and `server` are correctly configured when initializing the client. The server prefix can typically be extracted from your API key (the part after the hyphen).
affects: All versions
gotchaThe Mailchimp Marketing API enforces rate limits (e.g., up to 10 simultaneous connections), and excessive concurrent calls may result in HTTP 429 (Too Many Requests) or 403 errors. Large or long-running requests have a 120-second timeout.fixImplement proper pagination and rate-limiting strategies in your application. For bulk operations, consider using Mailchimp's Batch endpoint where available.
affects: All versions
Errors
Common errors & fixes
ApiClientError: The requested resource could not be found.
This error occurs when the ID for a Mailchimp resource (e.g., list ID, member ID, campaign ID) provided in the API call does not exist or is incorrect, or the endpoint path is malformed.
fixVerify that the resource ID (e.g., list_id, member_id) is correct and exists in your Mailchimp account, and ensure the API endpoint path is properly constructed according to the Mailchimp Marketing API documentation.
ApiClientError: Invalid Mailchimp API Key: You are accessing the wrong datacenter - your client library may not properly support our datacenter mapping scheme.
This error indicates that the provided Mailchimp API key is either incorrect, expired, or the 'server' prefix (datacenter) configured in your client does not match the datacenter associated with your API key.
fixLog into your Mailchimp account, navigate to 'API keys', verify you have an active API key, and ensure the 'server' configuration in your code (e.g., 'us1', 'us19') exactly matches the datacenter prefix found at the end of your API key.
ApiClientError: Bad Request - FNAME must be provided - Please enter a value.
This 'Bad Request' error, often accompanied by a 400 status code, means an API call attempted to create or update a resource (like adding a new list member) but failed to include a required field (e.g., first name, email address) as defined in Mailchimp's audience settings or the API schema.
fixCheck the Mailchimp API documentation for the specific endpoint or your audience settings within Mailchimp to identify all required merge fields (e.g., FNAME, LNAME) and ensure they are included with valid data in your request body.
ModuleNotFoundError: No module named 'mailchimp_marketing'
This Python error occurs if the `mailchimp-marketing` library is not installed in your environment or if there is a typo in the import statement, such as using a hyphen instead of an underscore in the package name.
fixFirst, ensure the library is installed using pip: `pip install mailchimp-marketing`. Then, correct your import statement to use the underscore: `import mailchimp_marketing as MailchimpMarketing`.
Upgrade
Version history
3.0.80latest on PyPI · released Nov 2, 2022
Audit
Dependencies
No dependency data recorded yet.