README

Validate Mailchimp API key format, detect common errors, and optionally verify connectivity — all without hitting the Mailchimp API until you're ready.

Author: Chimpmatic

Why This Exists

The most common support request for any Mailchimp integration is "Invalid API Key." The causes are always the same:

Extra whitespace when pasting
Missing datacenter suffix (-us4)
Truncated key (copied only part of it)
Revoked or disabled key

This library catches all of these before making an API call, giving your users clear error messages instead of a generic failure.

Need to get your Mailchimp API key first? See How to Get Your Mailchimp API Key for a one-click shortcut.

Installation

composer require chimpmatic/mailchimp-api-key-validator

Quick Start

use Chimpmatic\MailchimpKeyValidator\ApiKeyValidator;

$validator = new ApiKeyValidator();

// Format validation (no network call)
$result = $validator->validate('aaaaaaaaaabbbbbbbbbbccccccccccdd-us4');

if ($result->isValid()) {
    echo $result->getDatacenter(); // "us4"
    echo $result->getHash();       // "aaaaaaaaaabbbbbbbbbbccccccccccdd"
} else {
    foreach ($result->getErrors() as $error) {
        echo $error;
    }
}

Connectivity Verification

Optionally verify the key works against the Mailchimp API (requires curl):

$result = $validator->verifyConnectivity('aaaaaaaaaabbbbbbbbbbccccccccccdd-us4');

if ($result->isValid()) {
    echo 'Connected to Mailchimp!';
    echo $result->getHttpStatus(); // 200
}

What It Catches

Issue	Detection	Message
Empty key	Format check	`API key is empty.`
Leading/trailing whitespace	Format check	Warning + auto-trim
Internal whitespace	Format check	`Key contains whitespace characters.`
Missing `-us4` suffix	Format check	`Missing datacenter suffix.`
Wrong hash length	Format check	`Key hash is N characters, expected 32.`
Non-hex characters	Format check	`Key hash contains non-hexadecimal characters.`
Invalid datacenter format	Format check	`Datacenter "X" does not match expected format.`
Unknown datacenter	Format check	Warning (may be newer DC)
Revoked/disabled key	Connectivity check	`API key is rejected by Mailchimp.`
Insufficient permissions	Connectivity check	`API key lacks sufficient permissions.`

ValidationResult API

$result->isValid();         // bool — true if no errors
$result->getErrors();       // string[] — list of error messages
$result->getWarnings();     // string[] — list of warning messages
$result->hasWarnings();     // bool — true if warnings exist
$result->getSanitizedKey(); // string — trimmed key
$result->getHash();         // ?string — 32-char hex hash or null
$result->getDatacenter();   // ?string — datacenter ID or null
$result->getHttpStatus();   // ?int — HTTP status from connectivity check
$result->getSummary();      // string — human-readable summary

Requirements

PHP 7.4 or higher
curl extension (only for verifyConnectivity())

Testing

composer test

Or run PHPUnit directly:

vendor/bin/phpunit

chimpmatic / mailchimp-api-key-validator

Maintainers

Package info

Statistics

Security