Mailchimp API Key Validator

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

Links

• Packagist
• GitHub
• Issues
• How to Get Your Mailchimp API Key
• Chimpmatic — Contact Form 7 to Mailchimp

License

MIT License. Copyright (c) 2026 Chimpmatic.