How to implement a subscription in MailChimp via API

MailChimp is one of the most popular platforms for email marketing automation. It offers a powerful set of APIs that allow you to remotely manage mailing lists, subscribers, and campaigns. In this article, we’ll look at a simple example of subscribing a user via API and adding them to a mailing list.

To implement the subscription, we’ll use the following PHP code:

<?php
define('API_KEY', '***');
define('LIST_ID', '***');

//User data
$user_email = '***';
$user_first_name = '***';
$user_last_name = '***';

// MailChimp API URL
$member_id = md5(strtolower($user_email));
$data_center = substr(API_KEY,strpos(API_KEY,'-')+1);
$url = 'https://'.$data_center.'.api.mailchimp.com/3.0/lists/'.LIST_ID.'/members/'.$member_id;

// Member information
$json = json_encode([
	'apikey'        => API_KEY,
	'email_address' => $user_email,
	'status'        => 'subscribed',
	// 'status'        => 'unsubscribed',
	// 'status'        => 'cleaned',
	// 'status'        => 'pending',
	'merge_fields'  => [
		'FNAME'     => $user_first_name,
		'LNAME'     => $user_last_name
	]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, 'user:' . API_KEY);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
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);

$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "http code: ".$http_code;
echo "<pre dir='ltr'>$result = ";print_r(json_decode($result, true)); echo "</pre>";

Let’s take a closer look at the code above and break it down in more detail.
The constants must be filled with actual values, which can be obtained from the corresponding sections in your MailChimp account:

define('API_KEY', '***');
define('LIST_ID', '***');

Where:
API_KEY — your API key
LIST_ID — the ID of your mailing list

User data: email address, first name, and last name.

$user_email = '***';
$user_first_name = '***';
$user_last_name = '***';

In real usage, you’ll typically get this data from a database, POST/GET request, or another source.
Next, we form the API endpoint URL to which the request will be sent:

$member_id = md5(strtolower($user_email));
$data_center = substr(API_KEY,strpos(API_KEY,'-')+1);
$url = 'https://'.$data_center.'.api.mailchimp.com/3.0/lists/'.LIST_ID.'/members/'.$member_id;

Then, we build a structured array and convert it to JSON using `json_encode()`:

$json = json_encode([
	'apikey'        => API_KEY,
	'email_address' => $user_email,
	'status'        => 'subscribed',
	// 'status'        => 'unsubscribed',
	// 'status'        => 'cleaned',
	// 'status'        => 'pending',
	'merge_fields'  => [
		'FNAME'     => $user_first_name,
		'LNAME'     => $user_last_name
	]
]);

The example includes only the minimum required parameters to successfully subscribe a user.
Pay attention to the `status` parameter — it can be one of several values: `subscribed`, `unsubscribed`, `cleaned`, or `pending`.

⚠️ Note: Be careful when testing. Sometimes, especially with email addresses on mail.ru, the confirmation email might not arrive.

We then use PHP's CURL functions to send the data to the MailChimp server:

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, 'user:' . API_KEY);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
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);

$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

And display the response in the browser:

echo "http code: ".$http_code;
echo "
<pre dir='ltr'>$result = ";print_r(json_decode($result, true)); echo "</pre>";

The contents of the `$http_code` variable can be used to check the response status. If it’s not 200, an appropriate error message can be shown.
The `$result` variable contains the response from MailChimp. If there are any errors, you’ll find them there.
For more detailed information about available fields and possible responses, refer to the official MailChimp API documentation.