mailchimp3

library3.0.21pypypi✓ verified 85d ago

mailchimp3 is a Python client library for interacting with version 3 of the Mailchimp API. It provides a straightforward interface to manage contacts, lists, campaigns, and other Mailchimp resources. The library is currently at version 3.0.21 and maintains an active development status with updates for API changes and bug fixes.

communication http-networking crm-productivity

pip install mailchimp3

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MAILCHIMP3

mailchimp3

communicationpythonv3.0.21

Install

2.1s avg

Import

615ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.21 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.656s · 22.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.574s · 23MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MailChimp

✓ from mailchimp3 import MailChimp

✗ from mailchimp3.mailchimp import MailChimp

The primary client class is directly importable from the top-level package.

This quickstart demonstrates how to initialize the `MailChimp` client using an API key and an optional username, and then how to fetch all audience lists. It's best practice to use environment variables for sensitive credentials.

import os from mailchimp3 import MailChimp # It's recommended to store API keys and usernames in environment variables api_key = os.environ.get('MAILCHIMP_API_KEY', 'YOUR_MAILCHIMP_API_KEY') username = os.environ.get('MAILCHIMP_USERNAME', 'YOUR_MAILCHIMP_USERNAME') # Optional for basic auth # Initialize the MailChimp client # As of v2.1.0, arguments are mc_api and mc_user (username is optional) client = MailChimp(mc_api=api_key, mc_user=username) # Example: Fetch all lists try: lists = client.lists.all() print("Successfully fetched lists:") for l in lists['lists']: print(f" - {l['name']} (ID: {l['id']})") except Exception as e: print(f"An error occurred: {e}")

Debug

Known issues

breakingThe order of arguments for initializing the `MailChimp` client was reversed in version 2.1.0. Additionally, the authentication argument name changed from `mc_secret` to `mc_api`. The `username` argument (`mc_user`) became optional for basic authentication.

fix

Update your client initialization to `MailChimp(mc_api='YOUR_API_KEY', mc_user='YOUR_USERNAME')`. If you're using basic authentication, `mc_user` is optional.

affects: >=2.1.0

gotchaMailchimp is designed to work optimally with a single audience. Using multiple audiences can lead to duplicate contacts, inconsistent messaging, and increased costs. Instead, use tags or groups for segmentation within a single audience.

fix

Consolidate contacts into one master audience and utilize Mailchimp's tagging and grouping features for segmentation and targeted communication.

affects: All

gotchaMaintaining list hygiene is crucial. Regularly remove bounced emails, unsubscribed contacts, and inactive subscribers. Additionally, ensure all contacts have provided explicit consent for marketing, as failing to do so can lead to legal issues (e.g., GDPR, CAN-SPAM fines) and negatively impact email deliverability.

fix

Implement regular list cleaning processes and ensure all sign-up forms clearly communicate consent, following relevant data privacy regulations.

affects: All

breakingMailchimp's free plan has significant reductions starting in 2026. The contact limit will drop to 250, monthly sends to 500, and features like automations, A/B testing, and email scheduling will be removed. This may necessitate upgrading to a paid plan for many users.

fix

Review your Mailchimp usage and consider upgrading to a paid plan or exploring alternative services if your needs exceed the new free plan limits and features.

affects: >=2026-01-01

Errors

Common errors & fixes

TypeError: __init__() got an unexpected keyword argument 'mc_secret'

The authentication argument name changed from `mc_secret` to `mc_api` in `mailchimp3` v2.1.0 and later.

fix

When initializing the `MailChimp` client, use `mc_api='YOUR_API_KEY'` instead of `mc_secret='YOUR_API_KEY'`.

mailchimp3.exceptions.MailChimpError: HTTP 404 Not Found (details: Resource Not Found)

Attempting to access a Mailchimp resource (e.g., a list, member, or campaign) with an incorrect or non-existent ID, or an invalid template name.

fix

Verify that the IDs (list ID, member ID, campaign ID, etc.) and template names used in your API calls are accurate and correspond to existing resources in your Mailchimp account.

mailchimp3.exceptions.MailChimpError: HTTP 400 Bad Request (details: Your merge fields were invalid.)

Mailchimp list merge fields are often required and are case-sensitive. This error occurs if required merge fields are missing or if their names/values do not match the exact configuration in Mailchimp.

fix

Ensure all required merge fields (e.g., FNAME, LNAME) are provided in the payload for member creation/updates, and that their names precisely match the case and type defined in your Mailchimp list settings.

Upgrade

Version history

3.0.21latest on PyPI · released Jun 13, 2023

Audit

Dependencies

requestsrequiredUsed for making HTTP requests to the Mailchimp API.

Agent activity

37 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/charlesthk/python-mailchimp ↗

packagehttps://pypi.org/project/mailchimp3/ ↗

homepagehttps://mailchimp.com ↗