💡 This article is for you if...
1. You want a quick start alternative to reading through the vast amount of Mailchimp documentation.  
2. You’ve built your Mailchimp integration already but want to learn about common gotchas and best practices to make your integration more robust.  
3. You want a convenient summary of everything you need to know to build a Mailchimp documentation (how to build Auth, rate limits, etc)

Mailchimp is a popular email marketing platform that allows businesses to manage their email campaigns, automate their marketing efforts, and analyze their results. If your product needs to integrate with email marketing data, then you’ll probably need to build an integration with your customer’s Mailchimp.

Building a customer-facing Mailchimp integration can be complex and time-consuming, especially if you're not familiar with the Mailchimp API and its quirks. However, we're here to help! In this guide, we'll walk you through the process of building a Mailchimp integration, sharing our knowledge and best practices along the way.

If you’re unfamiliar with what native integrations are in the first place, you can reference our previous blog post aptly titled "what are native integrations?".

As a side note, I’ll be using the Vessel SDK to build this integration so I don’t have to worry about setting up authentication or handling any Mailchimp API quirks. However, If you don’t want to use Vessel, no worries! This guide is kept as generic as possible and will be useful regardless of how you decide to build your native Mailchimp integration.

Getting Setup For your Mailchimp Integration

Before you dive into writing code for your Mailchimp integration, there are a few logistical things you’ll want to get out of the way before we can begin making API calls.

Create a Mailchimp Test Account

Mailchimp doesn’t have developer-specific accounts, but you can create a free test account and populate it with test data. You can go ahead and sign up below and fill in a few campaigns and audience lists.

🔗 Free Mailchimp Account

Create A Mailchimp API Key

Mailchimp supports both OAuth and API key authentication. OAuth is always recommended when building customer-facing integrations and you’ll need to build OAuth to get your Mailchimp app approved.

However, for the purposes of development, it’s best to generate an API Key which will prevent the need to set up an OAuth app since that can be quite complex.

• Navigate to your Profile page by clicking your icon in the top right corner

• Click into “Extras” and scroll down to the API keys section

• Click on the “Create an API key” section and follow the prompt

Done! You’re now ready to start making API calls 🎉.

As an aside, if you’re using Vessel, you can skip this step since it will come with Mailchimp OAuth already set up.

The Mailchimp API at a Glance

Before we dive into building our Mailchimp integration, let's take a quick look at some important things to know about the Mailchimp API

Authentication

The first step to making an API call is to ask your user for permission to access their data. We do this by “installing” the OAuth app we created inside of their CRM instance.

During this process, your user will be shown a popup window that asks them to grant you permission to read and write their data.

OAuth is a complicated and nuanced topic, for brevity, I’m not going to touch on how to build out an OAuth flow since it’s not Mailchimp-specific.

If you’re new to OAuth and just need to get something going fast or don’t want to deal with the notorious headache of OAuth, you can use a framework like Vessel to handle it for you.

If you’d prefer to do this yourself, you can read the Mailchimp OAuth tutorial which is pretty thorough. Forewarning, the tutorial is very Mailchimp specific so if you know you’ll need to build other integrations in the future, I’d invest in doing more research so you understand how to build a more generic Auth flow since OAuth is an infamously difficult problem.

Regardless of how you choose to build authentication, the important part is that you’re able to get your user's credentials so you can push and pull data through the API.

Making an API Call

Now that you're able to authenticate your requests, you can begin making API calls to the Mailchimp API. In this section, we'll explore how to read and write data to the Mailchimp API in real-time.

Reading From the API

Reading data from the Mailchimp API is a common task when building a Mailchimp integration. Whether you need to fetch subscriber information or retrieve campaign data, the Mailchimp API provides endpoints to fetch this information.

When reading from the Mailchimp API, there are a few gotchas to watch out for:

• Domain prefix: Every Mailchimp API call must be prefixed with your customer’s “datacenter”.
• Filter and Sort: The Mailchimp API supports filtering and sorting for certain endpoints. You can use query parameters to filter and sort the data returned by the API which is highly recommended as the APIs can be slow.

Through Mailchimp API

Here's an example of how to make a GET request to fetch a list using the Mailchimp API:

const token = "YOUR_CUSTOMERS_ACCESS";
const listId = "YOUR_LIST_ID";
const datacenter = "YOUR_DATA_CENTER";

const url = `https://${datacenter}.api.mailchimp.com/3.0/lists/${listId}`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

‍

With Vessel

If you're using the Vessel SDK, you can simplify the process of making API calls to the Mailchimp API. Here's an example of how to use the Vessel SDK to fetch a list:

import Vessel from '@vesselapi/sdk';

const vessel = Vessel({
  apiKey: "YOUR_API_KEY",
  accessToken: "YOUR_CUSTOMERS_ACCESS_TOKEN"
});

const response = await vessel.unifications.marketingAutomation.lists.find({
  id: "YOUR_LIST_ID"
});

console.log(response);

Note that we can use the unified API for this call so that we don’t have to rebuild this flow if we want to support other marketing automation tools.

Writing to the API

Whether you need to add a new subscriber or update an existing campaign, the Mailchimp API provides endpoints to perform these actions.

When writing to the Mailchimp API, there are a few gotchas to watch out for:

• Batch writes: If you need to make updates or create many objects at once, it’s best to use the batch write endpoints to improve performance and also help avoid rate limit issues.
• Validation: The Mailchimp API validates the data you send in your requests. Make sure to follow the API documentation to ensure your data is in the correct format.

Through Mailchimp API

Here's an example of how to make a POST request to add a new subscriber using the Mailchimp API:

const token = "YOUR_API_KEY";
const listId = "YOUR_LIST_ID";
const datacenter = "YOUR_DATA_CENTER";

const url = `https://${datacenter}.mailchimp.com/3.0/lists/${listId}/members`;

const requestBody = { 
  email_address: "example@example.com", 
  status: "subscribed",
  merge_fields: {
    FNAME: "John",
    LNAME: "Doe"
  }
};

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"  
  },
  body: JSON.stringify(requestBody)
});

const data = await response.json();
console.log(data);

With Vessel

If you're using the Vessel SDK, you can simplify the process of making API calls to the Mailchimp API. Here's an example of how to use the Vessel SDK to add a new subscriber:

import Vessel from '@vesselapi/sdk';

const vessel = Vessel({
  apiKey: "YOUR_API_KEY"
});

// Add a new subscriber
const response = await vessel.unifications.marketing.contacts.create({
  listId: "YOUR_LIST_ID",
  email: "example@example.com",
  firstName: "John",
  lastName: "Doe"
});

console.log(response);

Again, we can use the unified API to avoid having to build this out for multiple marketing automation integrations.

Closing Thoughts

Publishing your Application

Once you've completed building your integration, you may want to consider publishing your application. Publishing your application allows other Mailchimp customers to discover and use your integration, giving you more exposure and potential users.

To publish your Mailchimp application, you'll need to apply to be a Mailchimp integration partner and submit your application for review. Once approved, your application will be listed in the Mailchimp Marketplace, where users can find and install it.

About Us

Hopefully, you found this article helpful for building out your native MailChimp integration. I know I certainly wish something like this existed when we built out our MailChimp integration.

If you decided to give Vessel a spin while following this tutorial, thank you. If you have any feedback while using the SDK, don’t hesitate to reach out at support@vessel.dev. We’re a team of engineers at heart and take every piece of feedback extremely seriously.

If you’re curious to learn more about why we started Vessel and how we view the future of customer-facing integrations, you can read more in our “what are native integration platforms” post.

On that note, if you ever have any questions about building a Mailchimp integration while you’re going through this tutorial, don't hesitate to reach out at zach@vessel.dev. I’ll be more than happy to personally help.