Mailchimp3 Python Client

Common errors

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

  cause 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)

  cause 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.)

  cause 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.

Warnings

• breaking The 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.
• gotcha Mailchimp 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.
• gotcha Maintaining 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.
• breaking Mailchimp'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.

Install

• pip install mailchimp3 Install with pip

Imports

• MailChimp
  wrong:

  from mailchimp3.mailchimp import MailChimp

  correct:

  from mailchimp3 import MailChimp

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

Quickstart

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}")