Mailchimp Subscriber Interest Groups with V3 API

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.

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.

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.

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
2define('MAILCHIMP_API', 'API_TOKEN');
3define('MAILCHIMP_LIST', 'LIST_ID');
4define('MAILCHIMP_INTEREST', 'INTEREST_ID');
5
6// Include the API Wrapper Class
7include('./Mailchimp.php');
8
9use \DrewM\Mailchimp\Mailchimp;
10
11// Instantiate class
12$Mailchimp = new Mailchimp(MAILCHIMP_API);
13
14// grab email address from request
15$email = $_REQUEST['email'];
16$result = '';
17
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  ));
25}
26
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')
3
4// Create MC API instance
5const mc_api = new Mailchimp(MAILCHIMP_API_KEY)
6
7// Call subscribe func
8const response = await create_subscriber({
9  email: 'example@email.com', 
10  list_id: LIST_ID, 
11  status: 'subscribed', 
12  interests: [INTEREST_ID]
13});
14
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]
25
26  try {
27    await api.post({ 
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  }
40
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  }
51}
52
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 }), {}) }
56}

References & Resources

• Mailchimp API PHP Class
• StackOverflow: Finding Mailchimp List IDs