MailChimp API v3.0 – Manage Subscriber using PHP & CURL

This article shows how you can use MailChimp API v3.0 with PHP and CURL to manage MailChimp subscribers. This includes adding subscribers to a list, editing/updating subscribers in a list, adding subscribers to a category/group of a list, fetching and displaying list & list id and groups and groups id as well.

Getting your list ID

The list ID is not the numeric ID of the list. It is a combination of random letter and number.

You will get the list ID from ‘List name and defaults’ page.

– Create a list on your MailChimp account
– Click on that list
– Click on the ‘Settings’ menu
– A dropdown with sub-menus is displayed
– Click on the ‘List name and defaults’ sub-menu.
– On that page, on the right side, you will find the list ID highlighted in red/maroon color.

This link can be helpful to get into the ‘List name and defaults’ page: Find your List ID

Subscribe customer/user to a list

You need an API Key to add subscribers to a mailchimp list. This article shows how you can get an API key on MailChimp: About API Keys.

The API Key is in the format as xxxxxxxxxxxxxxxxxx-us13.

Here,
xxxxxxxxxxxxxxxxxx = some random number and letter
us13 = server name, it can be us2, us3, us10, etc.

The other necessary thing is the list ID to which we will be adding subscribers. Procedure to get List ID is already mentioned above.

Now, let us suppose that we are going to add a subscriber with name Mukesh Chapagain and email as testing123@chapagain.com.np.

Here is the code to do so:

<?php
$email = 'testing123@chapagain.com.np';
$first_name = 'Mukesh';
$last_name = 'Chapagain';

$api_key = 'xxxxxxxxxxxxxxxxxxxxxxx-us13'; // YOUR API KEY

// server name followed by a dot. 
// We use us13 because us13 is present in API KEY
$server = 'us13.'; 

$list_id = 'xxxxxxxxxxxx'; // YOUR LIST ID

$auth = base64_encode( 'user:'.$api_key );
    
$data = array(
    'apikey'        => $api_key,
    'email_address' => $email,
    'status'        => 'subscribed',
    'merge_fields'  => array(
        'FNAME' => $first_name,
        'LNAME' => $last_name
        )   
    );
$json_data = json_encode($data);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://'.$server.'api.mailchimp.com/3.0/lists/'.$list_id.'/members/');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
    'Authorization: Basic '.$auth));
curl_setopt($ch, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, true);   
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);

$result = curl_exec($ch);

$result_obj = json_decode($result);

// printing the result obtained 
echo $result_obj->status;
echo '<br>';
echo '<pre>'; print_r($result_obj); echo '</pre>';
?>

Get Group/Interest Category inside a List

Suppose, you have added a group category / interest category inside a list. The group/interest category can again contain group/interest inside it. So, the depth/hierarchy is like below:

— List
    — Group/Interest Category
        — Group/Interest

The following code will fetch all the group/interest categories present inside a list.

<?php
$api_key = 'xxxxxxxxxxxxxxxxxxx-us13'; // your api key
$server = 'us13.'; // your server

$list_id = 'xxxxxxxxxxxxx'; // your list id

$auth = base64_encode( 'user:'.$api_key );
    
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://'.$server.'api.mailchimp.com/3.0/lists/'.$list_id.'/interest-categories');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
    'Authorization: Basic '.$auth));
curl_setopt($ch, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

$result = curl_exec($ch);

$result_obj = json_decode($result);

foreach ($result_obj->categories as $obj) {
    echo $obj->id . ' - ' . $obj->title;
    echo '<br />';
}

echo '<pre>'; print_r($result_obj); echo '</pre>';
?>

Get Groups/Interests inside a Group/Interest Category

A group/interest category can contain multiple groups/interests. The following code will fetch all the groups/interests present inside a group/interest category.

<?php
$api_key = 'xxxxxxxxxxxxxxxxxxx-us13'; // your api key
$server = 'us13.'; // your server

$list_id = 'xxxxxxxxxxxxx'; // your list id
$group_id = 'xxxxxxxxxxxx'; // your group id

$auth = base64_encode( 'user:'.$api_key );
    
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://'.$server.'api.mailchimp.com/3.0/lists/'.$list_id.'/interest-categories/'.$group_id.'/interests');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
    'Authorization: Basic '.$auth));
curl_setopt($ch, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

$result = curl_exec($ch);

$result_obj = json_decode($result);

foreach ($result_obj->interests as $obj) {
    echo $obj->id . ' - ' . $obj->name;
    echo '<br />';
}

echo '<pre>'; print_r($result_obj); echo '</pre>';
?>

Add Subscriber to a particular Interest/Group

In the second example above, we added user/customer to a particular list. We then discussed that a list can have interest/group categories and the interest/group category can further have multiple interests/groups associated with it.

The following code shows how to add user/customer to a particular interest/group (it’s not interest/group category but the interest/group present inside the interest/group category). For this, we need interest/group ID. We have seen in the above examples about how to get interest/group id.

<?php
$email = 'testing123@chapagain.com.np';
$memberHash = md5($email);

$first_name = 'Mukesh';
$last_name = 'Chapagain';

$api_key = 'xxxxxxxxxxxxxxxxxxxxxxx-us13'; // YOUR API KEY
$server = 'us13.'; // server name followed by a dot. We use us13 because us13 is present in API KEY

$list_id = 'xxxxxxxxxxxx'; // YOUR LIST ID
$interest = 'xxxxxxxxxxx'; // YOUR INTEREST/GROUP ID

$auth = base64_encode( 'user:'.$api_key );
    
$data = array(
    'apikey'        => $api_key,
    'email_address' => $email,
    'status'        => 'subscribed',
    'merge_fields'  => array(
        'FNAME' => $first_name,
        'LNAME' => $last_name
        ),
    'interests'     => array(
            $interest => true
            ),
    );
$json_data = json_encode($data);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://'.$server.'api.mailchimp.com/3.0/lists/'.$list_id.'/members/'.$memberHash);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
    'Authorization: Basic '.$auth));
curl_setopt($ch, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);

$result = curl_exec($ch);

$result_obj = json_decode($result);
    
echo $result_obj->status;
echo '<br>';
echo '<pre>'; print_r($result_obj); echo '</pre>';
?>

– The above code is also used to update subscriber’s information like first name, last name, etc.
– The above code can also be used to add new subscriber.

There is a nice and helpful example on github regarding MailChimp API v3 with PHP & CURL.

Hope this helps. Thanks.