MailChimp API 3.0 Working with Interest Groups

Description and ready-to-use examples for working with Interest Groups. How to subscribe a user with the specific interests in MailChimp API 3.0.

July 12, 2016 / #APIs, #HTTP API, #MailChimp

While working with my MailChimp synchronization plugin for WordPress I learnt some things about MailChimp interest groups. And I want to share this knowledge with you.

All the code below will work only with WordPress because of using wp_remote_get() and wp_remote_post() functions for establishing connection to MailChimp API.

How to Work with Interests?

Interests in MailChimp are like taxonomies in WordPress. Imagine that MailChimp list is a WordPress blog, then interest category is a taxonomy and interests are terms in this taxonomy.

MailChimp WordPress analogy
Lists Blogs
Interest Category Taxonomy
Interests Terms

What can we say looking at this table? Each Mailchimp list has separate interest categories and interests.

Having only one list with different interests means you can keep your MailChimp costs down as users are counted as separate subscribers for each list they appear on. A single list also allows people to unsubscribe easily. And of course you could send campaigns only for users with a specific interest.

If you want to add the interests, select a specific list in Lists, then go to Manage Subscribers > Groups. Groups are interest categories here, and each group is an interest.

MailChimp Interest Groups

The only strange thing is that I didn’t find any mention of interest IDs here. But the IDs are required when we work with MailChimp API. So I recommend you to use the code from the next part to retrieve interest IDs.

Get a specific Interest Category with all Interests in it

In the first loop we get all interest categories, in the second loop — interests in each of them.

// I recommend you not to echo all the code immediately, add it into the variable first
$output = '';
$api_key = 'YOUR API KEY';
$list_id = 'LIST ID TO RETRIEVE INTERESTS FROM';
$dc = substr( $api_key, strpos( $api_key, '-' ) + 1 ); // datacenter, it is the part of your api key - us5, us8 etc
$args = array(
 	'headers' => array(
		'Authorization' => 'Basic ' . base64_encode( 'user:'. $api_key )
	)
);
 
$response = wp_remote_get( 'https://'.$dc.'.api.mailchimp.com/3.0/lists/'.$list_id . '/interest-categories', $args );
$body = json_decode( wp_remote_retrieve_body( $response ) );
 
if ( wp_remote_retrieve_response_code( $response ) == 200 && $body->total_items > 0 ) {
	foreach ( $body->categories as $group ) :
 
		// we can skip hidden interests
		if( $group->type == 'hidden')
			continue;
 
		// heading, name of the Interest Category
		$output .= '<h3>' . $group->title . '</h3>';
 
		// connect to API to get interests from each category
		$response = wp_remote_get( 'https://'.$dc.'.api.mailchimp.com/3.0/lists/'.$list_id . '/interest-categories/' . $group->id . '/interests', $args );
		$body = json_decode( wp_remote_retrieve_body( $response ) );
 
		if ( wp_remote_retrieve_response_code( $response ) == 200 && $body->total_items > 0 ) {
			/* type of the interest group which can be set in MailChimp dashboard */
			switch( $group->type ) :
				case 'checkboxes':{
					foreach( $body->interests as $interest ){
						$output .= '<label><input value="' . $interest->id . '" name="' . $group->id . '" type="checkbox" /> ' . $interest->name . '</label><br />';
					}
					break;
				}
				case 'radio':{
					foreach( $body->interests as $interest ){
						$output .= '<label><input value="' . $interest->id . '" name="' . $group->id . '" type="radio" /> ' . $interest->name . '</label><br />';
					}
					break;
				}
				case 'dropdown':{
					$output .= '<select name="' . $group->id . '"><option value="">Please select...</option>';
					foreach( $body->interests as $interest ){
						$output .= '<option value="' . $interest->id . '">' . $interest->name . '</option>';
 
					}
					$output .= '</select>';
					break;
				}
				default:
				break;
			endswitch;
 
		} else {
			$output .= '<b>' . wp_remote_retrieve_response_code( $response ) . wp_remote_retrieve_response_message( $response ) . ':</b> ' . $body->detail;
		}
 
	endforeach;
} else {
	$output .= '<b>' . wp_remote_retrieve_response_code( $response ) . wp_remote_retrieve_response_message( $response ) . ':</b> ' . $body->detail;
}
echo $output;

Your form should look like this (but without Thickbox popup I guess).

Groups of Interest in MailChimp

How to Subscribe a user with an Interest

I tried to find clean and simple example of subscribing a user with an interest in MailChimp API 3.0 – with no luck. So, here is my WordPress-based example for you.

As you can see, all you need is a specific interest ID (not category ID). I recommend you to use the above code for obtaining IDs, because I didn’t find IDs in MailChimp dashboard.

$api_key = 'YOUR API KEY';
$email = 'SUBSCRIBER EMAIL';
$status = 'subscribed'; // subscribed, cleaned, pending
 
$args = array(
	'method' => 'PUT',
 	'headers' => array(
		'Authorization' => 'Basic ' . base64_encode( 'user:'. $api_key )
	),
	'body' => json_encode(array(
    		'email_address' => $email,
		'status'        => $status,
		'interests' => array(
			'INTEREST ID' => true, // add interest
			'INTEREST ID' => false, // remove interest
			'INTEREST ID' => false
    		)
	))
);
 
$response = wp_remote_post( 'https://' . substr($api_key,strpos($api_key,'-')+1) . '.api.mailchimp.com/3.0/lists/' . $list_id . '/members/' . md5(strtolower($email)), $args );
$body = json_decode( $response['body'] );
 
if ( $response['response']['code'] == 200 && $body->status == $status ) {
	echo 'The user has been successfully ' . $status . '.';
} else {
	echo '<b>' . $response['response']['code'] . $body->title . ':</b> ' . $body->detail;
}

If you have any questions or you would like to see more examples here, please leave a comment below.

Only the best of WordPress

once a week, no spam

Comments 2

  • Thanks for posting this, helped me out tremendously!

  • Martin StormJanuary 5, 2017 at 20:01

    Hi!

    Nice post!
    I’m trying to do this but something goes wrong.

    I have an hidden group in mailchimp with sub-interests.
    I can’t find the interests ids.

    I did a var_dump of the “$body” variable there is everything inside, including the names of my sub interests but the provided id doesn’t work.

    I hope you can help me.

    Thank you so much!

Leave your question or feedback

phpjsHTMLCSSSQLCode
Please, enter a comment
Please, enter a name
Incorrect email