Mailchimp Getting Started: API Keys & First Request (2026)

Getting started overview

Integrating with the Mailchimp API enables programmatic management of marketing campaigns, audience data, and reporting. This guide outlines the essential steps to get started: account creation, credential generation, and executing a foundational API request. The Mailchimp API is RESTful, utilizing HTTP methods (GET, POST, PUT, PATCH, DELETE) for resource manipulation and JSON for data exchange. Authentication is handled via API keys, which are passed as Bearer tokens in the Authorization header.

Mailchimp offers comprehensive API documentation, detailing endpoints for various functionalities, including audience management, campaign creation, and analytics. Official SDKs are available for several programming languages, simplifying interaction with the API by abstracting HTTP request construction and response parsing.

Before making your first API call, ensure you understand the core concepts of Mailchimp's data model, particularly "Audiences" (formerly "Lists") and "Members." An audience is a collection of contacts, and members are individual contacts within an audience. Most initial API interactions revolve around managing these resources.

Here's a quick reference for the getting started process:

Create an account and get keys

To begin using the Mailchimp API, you must first have an active Mailchimp account. Mailchimp offers a free plan that supports up to 500 contacts and 1,000 email sends per month, which is sufficient for initial API testing and development.

Account Creation

1. Navigate to the Mailchimp website.
2. Click "Sign Up Free" or a similar prompt.
3. Follow the on-screen instructions to create your account, providing an email address, username, and password.
4. Verify your email address to activate the account.

Generating an API Key

Mailchimp API keys serve as your authentication credentials. Each key is a unique string that grants access to your account's API resources. It is crucial to keep your API keys confidential to prevent unauthorized access.

1. Log in to your Mailchimp account.
2. Click on your profile icon (usually in the bottom-left or top-right corner) and select "Profile."
3. From the profile menu, navigate to "Extras" and then "API keys."
4. Under the "Your API Keys" section, click the "Create A Key" button.
5. A new API key will be generated and displayed. Copy this key immediately and store it securely. You will not be able to view the full key again after leaving this page, though you can generate new ones.

Identifying Your Server Prefix

Every Mailchimp API request requires a server prefix, which is specific to your account's data center. This prefix forms part of your API endpoint URL.

• The server prefix is typically derived from the last three characters of your API key. For example, if your API key is abcdef0123456789abcdef0123456789-us1, your server prefix is us1.
• Alternatively, you can find the server prefix in your Mailchimp account's URL when logged in. For instance, if your URL is https://us1.admin.mailchimp.com/, then us1 is your server prefix.

The base URL for API requests will follow the format https://<server-prefix>.api.mailchimp.com/3.0/. For example, https://us1.api.mailchimp.com/3.0/.

Your first request

A common first step is to add a new contact (member) to an existing audience. This verifies your API key and server prefix are correctly configured. Before you can add a member, you need an Audience ID. You can find this by navigating to Audience > All contacts > Settings > Audience name and defaults in your Mailchimp dashboard, or by using the List Audiences API endpoint.

Prerequisites

• Your Mailchimp API Key (e.g., YOUR_API_KEY)
• Your Server Prefix (e.g., us1)
• An existing Audience ID (e.g., YOUR_AUDIENCE_ID)

Using an Official SDK (Python Example)

Mailchimp provides official SDKs to simplify API interactions. Here's an example using the Python SDK to add a new member. First, install the SDK:

pip install mailchimp-marketing

Then, execute the following Python code:

import mailchimp_marketing as MailchimpMarketing
from mailchimp_marketing.api_client import ApiClientError

# Replace with your actual API key, server prefix, and audience ID
api_key = "YOUR_API_KEY"
server_prefix = "YOUR_SERVER_PREFIX" # e.g., us1
audience_id = "YOUR_AUDIENCE_ID"

client = MailchimpMarketing.Client({
    "api_key": api_key,
    "server": server_prefix
})

try:
    member_info = {
        "email_address": "[email protected]",
        "status": "subscribed", # or "pending", "unsubscribed", "cleaned"
        "merge_fields": {
            "FNAME": "Test",
            "LNAME": "User"
        }
    }
    response = client.lists.add_list_member(audience_id, member_info)
    print("Successfully added member:", response)
except ApiClientError as error:
    print("Error:", error.text)

Using cURL (Direct HTTP Request)

If you prefer to make a direct HTTP request without an SDK, you can use curl. Remember to replace the placeholders.

curl --request POST \
  --url 'https://YOUR_SERVER_PREFIX.api.mailchimp.com/3.0/lists/YOUR_AUDIENCE_ID/members' \
  --user 'anystring:YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"email_address": "[email protected]", "status": "subscribed", "merge_fields": {"FNAME": "Another", "LNAME": "User"}}'

A successful response will return a 200 OK status along with the details of the newly added member, including their unique ID.

Common next steps

Once you've successfully made your first API call, consider these common next steps to further integrate with Mailchimp:

• Explore Audience Management: Beyond adding members, learn to update existing contacts, retrieve member information, and manage audience segments. The Mailchimp List Members API reference provides detailed information on these operations.
• Campaign Creation: Programmatically create and send email campaigns. This involves defining campaign content, setting up target audiences, and scheduling sends. Review the Mailchimp Campaigns API documentation for various campaign types and settings.
• Webhooks: Implement webhooks to receive real-time notifications about events in your Mailchimp account, such as new subscriber additions, unsubscribes, or campaign sends. This eliminates the need for constant polling. Further details are available in the Mailchimp Webhooks guide.
• Error Handling: Implement robust error handling in your application. The Mailchimp API returns specific error codes and messages for different issues, which can help in debugging and user feedback. Familiarize yourself with Mailchimp's error handling guidelines.
• OAuth 2.0 Integration: If you are building an application for other Mailchimp users, consider implementing OAuth 2.0 for secure authorization without handling user credentials directly. Mailchimp's API supports OAuth 2.0 for third-party integrations.
• Utilize Batch Operations: For operations involving a large number of resources (e.g., adding many contacts), use Mailchimp's batch operations to improve efficiency and reduce API call limits. The Batch Operations API endpoint is designed for this purpose.

Troubleshooting the first call

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

• Incorrect API Key or Server Prefix: Double-check that your API key is correct and that the server prefix matches the one associated with your account. A common mistake is using the full API key in the server prefix field or vice-versa. The API key should be included in the Authorization header as a Bearer token, and the server prefix in the URL.
• Audience ID Mismatch: Ensure the Audience ID used in your request payload or URL path is valid and corresponds to an existing audience in your Mailchimp account. You can verify this in your Mailchimp dashboard under Audience > Settings > Audience name and defaults.
• Authentication Errors (401 Unauthorized): This typically indicates an issue with your API key. Confirm the key is active and correctly formatted in the Authorization: Bearer YOUR_API_KEY header. For curl, the --user 'anystring:YOUR_API_KEY' format handles basic authentication correctly, which Mailchimp maps to Bearer authentication.
• Bad Request (400 Bad Request): This often means your request body JSON is malformed or missing required fields. Check the Mailchimp API reference for the specific endpoint you are calling to ensure all mandatory fields are present and correctly formatted (e.g., email_address and status for adding a member). Ensure Content-Type: application/json is set in your headers.
• Network Connectivity: Verify your application can reach the Mailchimp API endpoints. Temporarily disable firewalls or proxies if you suspect they are interfering.
• Rate Limiting (429 Too Many Requests): While less likely on a first call, be aware that Mailchimp enforces rate limits. If you're rapidly testing, you might hit this. Implement exponential backoff for retries. Information on Mailchimp API rate limits is available in their developer guides.
• Check Mailchimp Status Page: Occasionally, the issue might be on Mailchimp's side. Check the Mailchimp Status Page for any ongoing outages or performance issues.
• Consult SDK Documentation: If you're using an SDK, refer to its specific documentation and examples. SDKs often have their own error handling mechanisms that can provide more specific insights.