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(1mo ago)00MITPHPPHP >=8.5

Since Mar 17Pushed 1mo 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 1mo ago

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 < 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

38

—

LowBetter than 85% of packages

Maintenance89

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

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

57d 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

[airesvsg/acf-to-rest-api

Exposes Advanced Custom Fields Endpoints in the WordPress REST API

1.4k75.0k](/packages/airesvsg-acf-to-rest-api)[humanmade/mercator

WordPress multisite domain mapping for the modern era.

529180.9k3](/packages/humanmade-mercator)[wordpress/mcp-adapter

Adapter for Abilities API, letting WordPress abilities to be used as MCP tools, resources or prompts

74855.8k1](/packages/wordpress-mcp-adapter)[wp-graphql/wp-graphql-woocommerce

WooCommerce bindings for WPGraphQL

69146.8k](/packages/wp-graphql-wp-graphql-woocommerce)[sybrew/the-seo-framework

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

47078.8k](/packages/sybrew-the-seo-framework)[pacely/mailchimp-apiv3

Simple API wrapper for Mailchimp API V3

95654.6k2](/packages/pacely-mailchimp-apiv3)

PHPackages © 2026

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