The Grouparoo Blog
Grouparoo allows you to connect your Customer and Product data to Mailchimp. Grouparoo collects all of your customer data in one place and makes it easy to sync your Profiles and Groups to other marketing tools. Mailchimp is a popular email marketing tool with great features and a robust API. However, there are some things to watch out for when integrating with Mailchimp that Grouparoo can help with.

Mailchimp setup
In Mailchimp, you will need to create a new API Key for Grouparoo to use. Visit Account -> Extras -> API Keys
to generate a new API Key.

In Grouparoo, Apps provide the credentials to be able to connect to other platforms. For Mailchimp, all you need to do is paste in the apiKey
from the Mailchimp page. At this point if you hit "Test Connection," you should see "Test Passed" and some data about your Mailchimp account.

From there, you can create a Destination and start exporting your Profiles and Groups. You can learn more about creating Destinations here
Implementation Details
One of the values of using an open source customer data platform (CDP) like Grouparoo is that you gain from the experience and attention from multiple companies using the same plugin so it works correctly in the real world.
Grouparoo uses the Mailchimp V3 API. Here are a few of the things we've learned about using it:
Rate Limiting
Mailchimp has a very strict 10-connections-at-once limit.
From https://mailchimp.com/developer/guides/marketing-api-conventions/#throttling
To improve connections and experiences for all our users, we use some connection limits. Each user account can have up to 10 simultaneous connections; you’ll receive an error message if you reach the limit. We do not throttle based on volume.
This limit means that no matter the size of your plan with Mailchimp, you cannot update more than 10 profiles at once. To solve this issue, Grouparoo implemented a parallelism
limit to use in our @grouparoo/mailchimp
package. We'll be sure that no matter how many background processes you are running, no more than 9 of them will ever be working on a Mailchimp import or export at a time. We know how to track pending jobs and can visualize this behavior for you in our Runs and Exports.
Generating the Mailchimp ID
To Mailchimp, the primary identifier of a customer is their email address. As a result, for all subsequent update PUT
calls, you'll need to know the mailchimpId
of the customer. Luckily, it's easy to calculate based on an MD5 has of the email address. We created a shared helper for this calculation for Node.js / Typescript:
import * as crypto from "crypto";
export function generateMailchimpId(email: string) {
return crypto
.createHash("md5")
.update(email.toLowerCase().trim())
.digest("hex");
}
Note how it is important to trim and to make the email address lowercase.
Clearing Data
One of Grouparoo's principles is to minimize the data you send to external parties. This principle is to keep your and your customers' data safe. Part of that story is letting you remove data from your Mailchimp profiles that you have previously sent. There is no explicit way to do this in the Mailchimp API, but we've learned that setting a value to empty string (""
) works, no matter the data type.
For example if you wanted to remove the first_name
MERGE VAR from a profile in Mailchimp, you would do the following:
const mergeFields = {
email: "person@example.com",
first_name: "",
};
const payload = {
email_address,
status: "subscribed",
merge_fields: mergeFields,
};
const method = exists ? "put" : "post";
const route = exists
? `/lists/${listId}/members/${generateMailchimpId(email_address)}`
: `/lists/${listId}/members`;
// where client is an instance of `mailchimp-api-v3`
// from https://www.npmjs.com/package/mailchimp-api-v3
await client[method](route, payload);
Tag Names
Mailchimp allows you to Tag Profiles, and that is how Grouparoo indicates Group membership. There are a few unintuitive rules about Mailchimp's Tags:
- They must be lowercase
- They can contain a space
... otherwise, Mailchimp will convert your tag names.
To that end, a good way to ensure you are sending data that will not be modified is to call toLocaleLowerCase()
on your tags before sending them.
Boolean Data
Mailchimp allows boolean MERGE VARS, but it still expects data to be sent to them as strings. So, be sure to convert true
to "true"
and false
to "false"
before sending a Profile to the Mailchimp API.
Summary
You can learn more about how to use Grouparoo to send data to Mailchimp on our Mailchimp Integration Page.
Tagged in Connections Engineering
See all of Evan Tahler's posts.
Evan is the CTO and co-founder of Grouparoo, an open source data framework that easily connects your data to business tools. Evan is an open-source innovator, and frequent speaker at software development conferences focusing on Product Management, Node.JS, Rails, and databases.
Learn more about Evan @ https://www.evantahler.com