Mailchimp Subscriber Interest Groups with V3 API

  • PublishedAugust 22, 2019
  • Length1 Minute
  • CategoryTutorials

How to find then use interest group IDs to refine list campaign targeting and boost engagement. Examples provided for Mailchimp V3 PHP and Node APIs.

Photo credit: Mathyas Kurmann on Unsplash

About the Author

Dan is a front end engineer working on design systems. Previous roles include: Huge, Cvent, Gifn, and PRPL. For more information, see here.

Questions & Comments

If you have feedback, view this post on GitHub and create an issue or open a pull request with edits. Thanks for reading!

A client recently asked me to update their PHP Mailchimp integration to support targeting subscribers based on interests. To my surprise, locating the interest ID was more involved than updating the existing API requests.

Before we get started, we'll need an API key which we'll use to access Mailchimp's API playground and authenticate API calls. If you already have an API key, skip ahead to the Finding the Interest ID section below.

Creating an API Key

In order to create new users using we'll first need to create an API key with access to our account. Sign into Mailchimp then go to the Account Settings > Extras > API Keys page then Create a Key.

Mailchimp API Playground: Enter API token

Finding the Interest ID

Now that we have an API key, we need to find the interest ID. To do that, we'll need to use the Mailchimp API Playground. Using the API Key we just created, log into the API Playground and follow the steps below to navigate through the ensuing screens to find the desired interest.

Mailchimp API Playground: Enter API token

Sign in to your account, it should look something like this.

First, select Lists then use the Subresources dropdown to select interest-categories. Find the relevant category in the list then use the Subresources dropdown again to access interests. You should now be presented with the list of relevant interests, click the name of the one we want an ID for and you should arrive on the screen above with all the information we'll need.

Mailchimp API Playground: Interest detail page

Usage in API Requests

PHP Example

Download this Mailchimp API wrapper class, and save it next to our script so it can be found by the include(./Mailchimp.php) call on line 7 below.

Next, we need the API Token created in the first section, as well as the List ID and Interest ID from the second. Replace API_TOKEN, LIST_ID, and INTEREST_ID in the constant definitions on lines 2–4.

1// Define API config constants
6// Include the API Wrapper Class
9use \DrewM\Mailchimp\Mailchimp;
11// Instantiate class
12$Mailchimp = new Mailchimp(MAILCHIMP_API);
14// grab email address from request
15$email = $_REQUEST['email'];
16$result = '';
18// if there's an address make the request to mailchimp, store the response
19if ($email != '') {
20 $result = $Mailchimp->post("lists/" . MAILCHIMP_LIST . "/members", array(
21 'email_address' => $email,
22 'status' => 'subscribed',
23 'interests' => array(MAILCHIMP_INTEREST => true),
24 ));
27// return status
28echo json_encode($result);

Node.js Example

Since writing the original version of this post, I was asked to add the same functionality to a Gatsby site hosted on Netlify. After obtaining necessary API information described above, see below for a JavaScript example or see here for a ready-to-use Node serverless function.

1// Node SDK
2const Mailchimp = require('mailchimp-api-v3')
4// Create MC API instance
5const mc_api = new Mailchimp(MAILCHIMP_API_KEY)
7// Call subscribe func
8const response = await create_subscriber({
9 email: '',
10 list_id: LIST_ID,
11 status: 'subscribed',
12 interests: [INTEREST_ID]
15// Create new subscriber
16async function create_subscriber({
17 email,
18 list_id,
19 status,
20 interests,
21 merge_fields = {}
22}, api) {
23 const path = `/lists/${list_id}/members`
24 let [statusCode, error] = [null, null]
26 try {
27 await{
28 path,
29 body: {
30 email_address: email,
31 status,
32 merge_fields,
33 ...format_interests(interests),
34 }
35 })
36 } catch (e) {
37 statusCode = e.status
38 error = e.message
39 }
41 return {
42 created: !error,
43 error_response: { statusCode, error },
44 success_response: {
45 email,
46 subscribed: true,
47 existing_member: false,
48 profile_updated: false,
49 },
50 }
53// convert from String[] to interest object of `{ [id]: status }` shape
54function format_interests(arr = []) {
55 return { interests: arr.reduce((acc, cur) => ({ ...acc, [cur]: true }), {}) }

References & Resources