README

Subscribe contacts to Mailchimp audiences with merge fields. Clean OOP, zero dependencies, PHP 8.5+.

Author: Chimpmatic

Why This Exists

Adding a subscriber to Mailchimp through the API requires building the right payload, hashing the email, choosing the correct endpoint, and handling upsert logic. This library wraps all of that into a single method call.

Built for Contact Form 7 to Mailchimp integrations, but works with any PHP application.

Requirements

• PHP 8.5 or higher (uses readonly classes and enums)
• curl extension

A fatal error (E_USER_ERROR) is triggered if loaded on PHP < 8.5. The library will not run on older versions.

Installation

composer require chimpmatic/mailchimp-subscriber

Quick Start

use Chimpmatic\Subscriber\Subscriber;
use Chimpmatic\Subscriber\Contact;

$subscriber = new Subscriber('your-api-key-us4');

$contact = new Contact('john@example.com', [
    'FNAME' => 'John',
    'LNAME' => 'Doe',
]);

$result = $subscriber->subscribe('abc123def4', $contact);

echo $result->getSummary();
// "Added john@example.com to audience abc123def4 — status: subscribed"

Subscribe with Merge Fields

use Chimpmatic\Subscriber\Subscriber;
use Chimpmatic\Subscriber\Contact;

$subscriber = new Subscriber('your-api-key-us4');

$contact = new Contact('jane@example.com', [
    'FNAME'    => 'Jane',
    'LNAME'    => 'Smith',
    'BIRTHDAY' => '03/15',
    'PHONE'    => '+1-555-0100',
]);

$result = $subscriber->subscribe('abc123def4', $contact);

if ($result->isSubscribed()) {
    echo "Subscribed successfully!";
}

Convenience Method

// Skip creating a Contact object
$result = $subscriber->subscribeEmail(
    audienceId: 'abc123def4',
    email: 'user@example.com',
    mergeFields: ['FNAME' => 'User'],
);

Double Opt-In (Pending)

use Chimpmatic\Subscriber\SubscriptionStatus;

$result = $subscriber->subscribe(
    audienceId: 'abc123def4',
    contact: $contact,
    status: SubscriptionStatus::Pending,
);

if ($result->isPending()) {
    echo "Confirmation email sent!";
}

Check Member Status

$status = $subscriber->getMemberStatus('abc123def4', 'user@example.com');

if ($status === null) {
    echo "Not subscribed";
} else {
    echo $status->value; // "subscribed", "pending", "unsubscribed", etc.
}

Error Handling

use Chimpmatic\Subscriber\ApiException;

try {
    $subscriber = new Subscriber('your-api-key-us4');
    $subscriber->subscribeEmail('abc123def4', 'user@example.com');
} catch (\InvalidArgumentException $e) {
    // Bad API key format or invalid email
} catch (ApiException $e) {
    // API error (401, 404, network failure)
}

Finding Your Audience ID

Need to find your Audience ID and merge fields? Use mailchimp-audience-finder:

composer require chimpmatic/mailchimp-audience-finder

Need your API key first? See How to Get Your Mailchimp API Key.

For a guide on merge fields and tags, see Mailchimp Audience Fields and Merge Tags.

Links

• Packagist
• GitHub
• Issues
• Connect Contact Form 7 with Mailchimp
• How to Get Your Mailchimp API Key
• Mailchimp Audience Fields and Merge Tags
• Chimpmatic — Contact Form 7 to Mailchimp

License

MIT License. Copyright (c) 2026 Chimpmatic.