Marketing API Quick Start

This guide will give you everything you need to start using the Mailchimp Marketing API to manage audiences, control automation workflows, sync email activity with your database, and more. We’ll walk through generating your API key, installing the client library for your preferred language, and making your first API call—a simple request to the Ping endpoint.

If you don't have a Mailchimp account already, you’ll need to create one in order to use the API.

The simplest way to authenticate a request to the Marketing API is using an API key. 

Here’s how you can generate one for yourself: 

1. Navigate to the API Keys section of your Mailchimp account.

2. Click Create New Key and give it a descriptive name that will remind you which application it’s used for. Copy the generated key immediately and store it in a secure location. You won’t be able to see or copy the key once you finish generating it.

If you’re creating integrations that require access to Mailchimp on behalf of other Mailchimp users, you’ll want to set up authentication via Oauth 2 instead. 

You can make calls to the Marketing API with whichever method you usually use to make HTTP requests, but Mailchimp offers client libraries that make interacting with the API even simpler. 

To install the client library for your preferred language:

# No client installation necessary; just using curl

To test that you have everything set up correctly, we’ll make a simple request to the Ping endpoint. Hitting this endpoint acts as a health check on the Mailchimp API service; it won’t affect your account in any way. 

To find the value for the server parameter used in mailchimp.setConfig, log into your Mailchimp account and look at the URL in your browser. You’ll see something like https://us19.admin.mailchimp.com/; the us19 part is the server prefix. Note that your specific value may be different.

# install jq: https://stedolan.github.io/jq/download/

dc="YOUR_DC"
apikey="YOUR_API_KEY"

curl -sS \
  "https://${dc}.api.mailchimp.com/3.0/ping" \
  --user "anystring:${apikey}" | jq -r

If everything was set up correctly and the request to ping was a success, the response should look like the following:

{
   "health_status": "Everything's Chimpy!"
}

Now that you’re successfully making authenticated requests to the API with your API key and client library of choice, you’re ready to dive into the Mailchimp Marketing API. 

The first thing you may want to do is learn how to create your first audience and add new contacts to that audience using the API. You may also want to familiarize yourself with the Marketing API docs, which outline some of the common conventions you’ll run into across the API, or browse the extensive API Reference documentation.