Mailchimp Marketing Python Client

Warnings

• gotcha Mailchimp 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.
  Fix: Consolidate 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.
• breaking As 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.
  Fix: If 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.
• gotcha All 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.
  Fix: Ensure 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).
• gotcha The 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.
  Fix: Implement proper pagination and rate-limiting strategies in your application. For bulk operations, consider using Mailchimp's Batch endpoint where available.

Install

• pip install mailchimp-marketing Install latest version

Imports

• Client

  import mailchimp_marketing as MailchimpMarketing
  client = MailchimpMarketing.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: ...

Quickstart

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