How to Add/Update Subscribers with Tags to Mailchimp Using PHP/Laravel

If you’re building a web app and need to add users to a Mailchimp audience programmatically, you can do it easily using PHP/Laravel and the Mailchimp API.
In this post, I’ll show you how to add or update a subscriber, apply tags, and store merge fields like first name and last name.

Step 1: Set Up Your Mailchimp API Key

You can generate your API key from the Mailchimp dashboard:

• Go to Account → Extras → API Keys
• Create a new key and copy it

Example:

$apiKey = 'YOUR_API_KEY';

Step 2: Get Your Audience (List) ID

To find your audience ID:

• Navigate to Audience → Audience settings
• Copy the Audience ID

Example:

$listId = 'YOUR_LIST_ID';

Step 3: Identify Your Server Prefix

Your Mailchimp server prefix is visible in the Mailchimp dashboard URL.

Example:

https://us18.admin.mailchimp.com/...
So your server prefix would be:

$server = 'us18';

Step 4: Prepare the Subscriber Data

Next, collect user data (usually from a form request) and define any tags you want to apply.

$email = $request->email;
$tags = ['Tag 1']; // You can add multiple tags
$data = [
    'email_address' => $email,
    'merge_fields' => [
        'FNAME' => $request->fname,
        'LNAME' => $request->lname,
    ],
    'status_if_new' => 'subscribed',
    'tags' => $tags
];
$jsonData = json_encode($data);

Step 5: Build the Mailchimp API URL

Mailchimp identifies list members using an MD5 hash of the lowercase email address.

$url = 'https://' . $server . '.api.mailchimp.com/3.0/lists/' 
     . $listId . '/members/' . md5(strtolower($email));

Step 6: Send the PUT Request Using cURL

We’ll use a PUT request so the subscriber is created if new or updated if they already exist.

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, 'user:' . $apiKey);
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_POSTFIELDS, $jsonData);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode == 200) {
    echo "Subscriber added or updated successfully!";
} else {
    echo "Error: " . $response;
}

Step 7: One Complete PHP Example

Below is the full working PHP example that adds or updates a subscriber in Mailchimp, applies tags, and saves merge fields like first and last name.

<?php
// Mailchimp configuration
$apiKey = 'YOUR_API_KEY';          // Mailchimp API key
$listId = 'YOUR_LIST_ID';          // Audience ID
$server = 'us18';                  // Server prefix (e.g. us18)

// Subscriber data (example from form request)
$email = $request->email;
$fname = $request->fname;
$lname = $request->lname;

// Tags
$tags = ['Tag 1'];

// Prepare data
$data = [
    'email_address' => $email,
    'merge_fields' => [
        'FNAME' => $fname,
        'LNAME' => $lname,
    ],
    'status_if_new' => 'subscribed',
    'tags' => $tags
];

// Convert data to JSON
$jsonData = json_encode($data);

// Mailchimp API endpoint
$url = 'https://' . $server . '.api.mailchimp.com/3.0/lists/' 
     . $listId . '/members/' . md5(strtolower($email));

// Initialize cURL
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, 'user:' . $apiKey);
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_POSTFIELDS, $jsonData);

// Execute request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// Handle response
if ($httpCode === 200) {
    echo "Subscriber added or updated successfully!";
} else {
    echo "Mailchimp API Error: " . $response;
}

Notes

• PUT ensures the subscriber is created if they don’t exist, or updated if they do.
• Tags help segment users for campaigns and automations.
• merge_fields allow you to store additional user data like first and last names.

Conclusion

With just a few lines of PHP, you can integrate Mailchimp subscriptions into your web app, manage audience tags, and keep subscriber data organized automatically. This approach works perfectly for partners, customers, and any segmented email campaigns.

Comments

[Mohsin Shah]

Excellent walkthrough for integrating Mailchimp with PHP. Covers subscriber upsert using PUT, MD5 email hashing, tags, and merge fields in a clean and practical way. The complete working example saves a lot of development time.