Mailchimp API Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with the Mailchimp API involves a sequence of steps designed to ensure secure and authorized access to your Mailchimp account data. This guide focuses on the foundational requirements for making your first successful API call. The process begins with account creation, followed by the generation of an API key, and concludes with executing a basic request. This foundational setup is critical for developing applications that interact with Mailchimp's extensive feature set, including audience management, campaign creation, and marketing automation.

The Mailchimp API adheres to RESTful principles, utilizing standard HTTP methods (GET, POST, PATCH, PUT, DELETE) for resource manipulation. Responses are typically formatted in JSON. Authentication for direct API access is primarily handled via API keys, which are unique identifiers linked to a user's Mailchimp account. For third-party integrations requiring user consent, Mailchimp also supports OAuth 2.0 for secure authorization.

Before proceeding, ensure you have an active Mailchimp account. If you do not, the initial steps will guide you through the signup process. Access to the API is available across all Mailchimp plans, including the free tier, though certain advanced features or higher rate limits may be tied to paid subscriptions. For details on plan features, refer to the Mailchimp pricing page.

Here's a quick reference table outlining the getting started process:

Create an account and get keys

To begin interacting with the Mailchimp API, you first need a Mailchimp account. If you already have one, you can proceed to generating an API key. Otherwise, navigate to the Mailchimp developer portal and follow the prompts to create an account. Mailchimp offers a free plan that supports up to 500 contacts, which is sufficient for initial API testing and development.

Generating your API key

Once your account is set up and you are logged in, follow these steps to generate your API key:

1. Log in to your Mailchimp account.
2. Click on your profile icon in the bottom left corner of the dashboard.
3. Select Account & Billing from the dropdown menu.
4. Navigate to the Extras menu and click on API keys.
5. Under the "Your API keys" section, click the Create A Key button.
6. A new API key will be generated. Copy this key immediately, as it will be displayed only once in its entirety for security reasons.

This API key acts as your password for API requests. Keep it secure and do not expose it in client-side code or public repositories. For server-side applications, it is recommended to store your API key as an environment variable or in a secure configuration management system rather than hardcoding it directly into your application's source code.

Identifying your data center (dc)

The Mailchimp API base URL is dynamic, depending on the data center where your account is hosted. The structure is https://<dc>.api.mailchimp.com/3.0/. The <dc> prefix is crucial for routing your requests correctly. You can typically find your data center prefix in one of two ways:

• From your API key: The last digits of your API key (e.g., ...-us1, ...-eu2) indicate your data center. The part after the hyphen is your <dc>.
• From your Mailchimp account URL: When you are logged into your Mailchimp account, the URL in your browser's address bar will often contain the data center prefix (e.g., https://us1.admin.mailchimp.com/).

For example, if your API key ends with -us14, your data center is us14, and your base URL will be https://us14.api.mailchimp.com/3.0/.

Your first request

With your API key and data center identified, you can now make your first API call. A common starting point is to list your Mailchimp audiences (previously known as lists). This request verifies your credentials and demonstrates a successful interaction with the API.

Example: List audiences

We'll use cURL for this example, a widely available command-line tool for making HTTP requests. Replace YOUR_API_KEY with the key you generated and YOUR_DC with your data center prefix.

curl --request GET \
  --url 'https://YOUR_DC.api.mailchimp.com/3.0/lists' \
  --user 'anystring:YOUR_API_KEY' \
  --include

Let's break down this cURL command:

• --request GET: Specifies the HTTP GET method, as we are retrieving resources.
• --url 'https://YOUR_DC.api.mailchimp.com/3.0/lists': This is the endpoint for listing all audiences in your Mailchimp account. Ensure you replace YOUR_DC with your actual data center.
• --user 'anystring:YOUR_API_KEY': This sends your API key for authentication. The format is username:password for Basic Authentication. Mailchimp's API treats any non-empty string as the username and your API key as the password.
• --include: This option tells cURL to include the HTTP response headers in the output, which can be helpful for debugging.

Expected successful response

A successful response (HTTP status code 200 OK) will return a JSON object containing an array of your Mailchimp audiences. If you have no audiences yet, the lists array will be empty. An example successful response might look like this:

HTTP/1.1 200 OK
Server: openresty
Content-Type: application/json; charset=utf-8
...

{
  "lists": [
    {
      "id": "YOUR_LIST_ID",
      "name": "My First Audience",
      "contact": {
        "company": "Example Company",
        ...
      },
      "stats": {
        "member_count": 0,
        ...
      }
      // ... more list details
    }
  ],
  "total_items": 1,
  "_links": [
    // ... pagination and related links
  ]
}

The presence of a lists array and a total_items count indicates that your API key is valid, and your request was correctly routed and processed by the Mailchimp API.

Common next steps

After successfully making your first API call, you can explore various functionalities offered by the Mailchimp API. Here are some common next steps:

1. Add a New Member to an Audience: Use the POST /lists/{list_id}/members endpoint to add new subscribers. This is a fundamental operation for collecting and managing contacts. You will need an audience_id, which you can retrieve from the previous "List Audiences" call.
2. Update a Member's Status: Utilize the PATCH /lists/{list_id}/members/{subscriber_hash} endpoint to update an existing member's subscription status (e.g., from pending to subscribed, or to opt-out). The subscriber_hash is an MD5 hash of the lowercase email address.
3. Create a Campaign: Programmatically create email campaigns using the POST /campaigns endpoint. You can define content, recipients, and scheduling.
4. Explore Webhooks: Set up webhooks to receive real-time notifications about events in your Mailchimp account, such as new subscribers, unsubscribes, or profile updates. This allows for event-driven integrations without constant polling. For more information, consult the MDN Web Docs on webhooks.
5. Implement OAuth 2.0 (for public integrations): If you are building an application for other Mailchimp users, you should implement OAuth 2.0 to securely connect to their accounts without handling their API keys directly. The Mailchimp Authentication Guide provides detailed instructions.
6. Consult the API Reference: Dive deeper into the extensive Mailchimp API reference documentation to discover all available endpoints and their specific parameters for advanced functionalities.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for the Mailchimp API:

• Invalid API Key (HTTP 401 Unauthorized):
  • Symptom: Response indicates 401 Unauthorized or Invalid API Key.
  • Check: Ensure your API key is copied correctly without extra spaces. Verify that the --user 'anystring:YOUR_API_KEY' format is precise in your cURL command. Generate a new key if uncertain about the existing one.
  • Reference: Review the Mailchimp API Authentication Guide for correct key usage.
• Incorrect Data Center (HTTP 404 Not Found or 5xx Server Error):
  • Symptom: Response is 404 Not Found, 500 Internal Server Error, or a connection error.
  • Check: Confirm that the <dc> prefix in your URL (e.g., us14) matches the data center associated with your account and API key. Double-check the last part of your API key (e.g., ...-us14).
  • Example: If your key ends in -us14, your URL should start with https://us14.api.mailchimp.com/3.0/.
• Missing Required Parameters (HTTP 400 Bad Request):
  • Symptom: Response is 400 Bad Request, often with a message detailing missing or invalid parameters.
  • Check: While listing audiences typically doesn't require extra parameters, other endpoints do. Refer to the specific endpoint's documentation in the Mailchimp API Reference to ensure all required fields are included in your request body.
• Rate Limiting (HTTP 429 Too Many Requests):
  • Symptom: Response is 429 Too Many Requests.
  • Check: If you're making many requests in a short period, you might hit rate limits. Implement exponential backoff in your application to retry requests after a delay.
  • Guidance: Mailchimp's API has specific rate limits depending on your plan.
• Network Issues:
  • Symptom: Connection timeouts or immediate failures.
  • Check: Verify your internet connection. Ensure no firewalls or proxy settings are blocking outgoing HTTP requests from your environment.