README

Find your Mailchimp Audience ID and merge fields using your API key. Zero config, one method call.

Author: Chimpmatic

Why This Exists

Every Mailchimp integration needs two things: an API key and an Audience ID. Getting the API key is straightforward — but finding the Audience ID means clicking through Audience → Settings → Audience name and defaults, and then you still need to know which merge fields (FNAME, LNAME, BIRTHDAY, etc.) are available.

This library does it in one call. Pass your API key, get back every audience with its ID, member count, merge fields, and opt-in settings.

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.

Requirements

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

A runtime warning is triggered if loaded on PHP < 8.5.

Installation

composer require chimpmatic/mailchimp-audience-finder

Quick Start

use Chimpmatic\AudienceFinder\AudienceFinder;

$finder = new AudienceFinder('your-api-key-us4');

// Get all audiences
$audiences = $finder->findAll();

foreach ($audiences as $audience) {
    echo $audience->id;          // "abc123def4"
    echo $audience->name;        // "Newsletter Subscribers"
    echo $audience->memberCount; // 1500
    echo $audience->doubleOptIn; // true

    // Merge fields included automatically
    foreach ($audience->mergeFields as $field) {
        echo $field->tag;         // "FNAME"
        echo $field->name;        // "First Name"
        echo $field->type;        // "text"
        echo $field->required;    // true
        echo $field->getMergeTag(); // "*|FNAME|*"
    }
}

Find by ID

$audience = $finder->findById('abc123def4');

echo $audience->getSummary();
// "Newsletter Subscribers (ID: abc123def4) — 1500 members, 4 merge fields, double opt-in: yes"

Find by Name

$audience = $finder->findByName('newsletter');
// Case-insensitive partial match — returns first match or null

Working with Merge Fields

$audience = $finder->findById('abc123def4');

// Find a specific field
$fname = $audience->getMergeFieldByTag('FNAME');
echo $fname->name;         // "First Name"
echo $fname->getMergeTag(); // "*|FNAME|*"

// Get all required fields
$required = $audience->getRequiredFields();
// Returns only fields where required = true

Get Merge Fields Separately

$fields = $finder->getMergeFields('abc123def4');

foreach ($fields as $field) {
    echo sprintf('%s (%s) — %s', $field->tag, $field->type, $field->name);
    // "FNAME (text) — First Name"
    // "BIRTHDAY (birthday) — Birthday"
}

Error Handling

use Chimpmatic\AudienceFinder\ApiException;

try {
    $finder = new AudienceFinder('invalid-key');
    $finder->findAll();
} catch (\InvalidArgumentException $e) {
    // Bad API key format
} catch (ApiException $e) {
    // API error (401, 404, network failure)
}

Links

• Packagist
• GitHub
• Issues
• 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.