Marketing API Quick Start

At a glance

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.

Create an account

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

Generate your API key

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. If you already have an API key listed and you’d like to use it for your application, simply copy it. 

Otherwise, click Create a Key and give it a descriptive name that will remind you which application it’s used for.

Note: It’s important to remember that your Mailchimp API key provides full account access, so you should keep it secure, as you would with a password. Because of the potential security risks associated with exposing account API keys, Mailchimp does not support client-side calls to the Marketing API using CORS requests, nor should API keys be used in mobile apps.

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. 

Install the client library for your language

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:

Install your client library

# No client installation necessary; just using curl

Make your first API call

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.

Make your first API call

# 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:

Ping endpoint response

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

Next steps

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 some of the common conventions you’ll run into across the Marketing API endpoints.

If you’re looking for more information about what you can do with the Marketing API, check out the full list of Marketing API guides, or browse the extensive API Reference documentation.