PHPackages                             chimpmatic/mailchimp-audience-finder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. chimpmatic/mailchimp-audience-finder

ActiveLibrary[API Development](/categories/api)

chimpmatic/mailchimp-audience-finder
====================================

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

v1.0.0(6d ago)00MITPHPPHP &gt;=8.5

Since Mar 17Pushed 6d agoCompare

[ Source](https://github.com/chimpmatic/mailchimp-audience-finder)[ Packagist](https://packagist.org/packages/chimpmatic/mailchimp-audience-finder)[ Docs](https://chimpmatic.com)[ RSS](/packages/chimpmatic-mailchimp-audience-finder/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (2)Used By (0)

Mailchimp Audience Finder
=========================

[](#mailchimp-audience-finder)

[![Latest Version](https://camo.githubusercontent.com/82bdfddf63475753c41841029bec7d46b456a58b36a42f126c4427d3ba834a31/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6368696d706d617469632f6d61696c6368696d702d61756469656e63652d66696e6465722e737667)](https://packagist.org/packages/chimpmatic/mailchimp-audience-finder)[![PHP Version](https://camo.githubusercontent.com/754318cadf6d709ad4c4a99d7006d62d68153fbbf879b5538b7ee6620e413cd2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6368696d706d617469632f6d61696c6368696d702d61756469656e63652d66696e6465722e737667)](https://packagist.org/packages/chimpmatic/mailchimp-audience-finder)[![License](https://camo.githubusercontent.com/9cf769b9193443d74c2b70bf78e89f06161ff70f9456d0c086aedb6fd3465d39/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6368696d706d617469632f6d61696c6368696d702d61756469656e63652d66696e6465722e737667)](https://github.com/chimpmatic/mailchimp-audience-finder/blob/main/LICENSE)

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

**Author:** [Chimpmatic](https://chimpmatic.com)

Why This Exists
---------------

[](#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](https://chimpmatic.com/how-to-get-your-mailchimp-api-key).

For a guide on merge fields and tags, see [Mailchimp Audience Fields and Merge Tags](https://chimpmatic.com/mailchimp-audience-fields-and-merge-tags).

Requirements
------------

[](#requirements)

- **PHP 8.5 or higher** (uses `readonly` classes and named arguments)
- `curl` extension

A runtime warning is triggered if loaded on PHP &lt; 8.5.

Installation
------------

[](#installation)

```
composer require chimpmatic/mailchimp-audience-finder
```

Quick Start
-----------

[](#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
----------

[](#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
------------

[](#find-by-name)

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

Working with Merge Fields
-------------------------

[](#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
---------------------------

[](#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
--------------

[](#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
-----

[](#links)

- [Packagist](https://packagist.org/packages/chimpmatic/mailchimp-audience-finder)
- [GitHub](https://github.com/chimpmatic/mailchimp-audience-finder)
- [Issues](https://github.com/chimpmatic/mailchimp-audience-finder/issues)
- [How to Get Your Mailchimp API Key](https://chimpmatic.com/how-to-get-your-mailchimp-api-key)
- [Mailchimp Audience Fields and Merge Tags](https://chimpmatic.com/mailchimp-audience-fields-and-merge-tags)
- [Chimpmatic — Contact Form 7 to Mailchimp](https://chimpmatic.com)

License
-------

[](#license)

MIT License. Copyright (c) 2026 [Chimpmatic](https://chimpmatic.com).

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance98

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

6d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e0fe8014730461a907cfbc1b54ca0783ef523afa729ea89739cf96feaa78880e?d=identicon)[chimpmatic](/maintainers/chimpmatic)

---

Top Contributors

[![chimpmatic](https://avatars.githubusercontent.com/u/73747745?v=4)](https://github.com/chimpmatic "chimpmatic (1 commits)")

---

Tags

wordpressmailchimpcontact-form-7merge-tagsaudience-idlist-idmerge-fields

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/chimpmatic-mailchimp-audience-finder/health.svg)

```
[![Health](https://phpackages.com/badges/chimpmatic-mailchimp-audience-finder/health.svg)](https://phpackages.com/packages/chimpmatic-mailchimp-audience-finder)
```

###  Alternatives

[sybrew/the-seo-framework

An automated, advanced, accessible, unbranded and extremely fast SEO solution for any WordPress website.

46876.8k](/packages/sybrew-the-seo-framework)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
