README

A Laravel package for the Mailchimp Marketing API with OAuth 2.0 support, built on SaloonPHP.

Installation

composer require sensson/laravel-mailchimp

Publish the config file:

php artisan vendor:publish --tag="mailchimp-config"

Add your OAuth credentials to .env. You can create an OAuth app in your Mailchimp account under Registered Apps:

MAILCHIMP_CLIENT_ID=your-client-id
MAILCHIMP_CLIENT_SECRET=your-client-secret
MAILCHIMP_REDIRECT_URI=https://your-app.com/mailchimp/callback

OAuth 2.0

Redirect the user to Mailchimp to authorize your app:

use Sensson\Mailchimp\Facades\Mailchimp;

return redirect()->to(Mailchimp::auth()->getAuthorizationUrl());

Handle the callback to get an access token and data center:

use Sensson\Mailchimp\Enums\ServerPrefix;

$token = Mailchimp::auth()->exchangeToken($request->code);
$metadata = Mailchimp::auth()->getMetadata($token);
$dc = ServerPrefix::from($metadata->json('dc'));

Store $token and $dc for later use. The MailchimpAuth cast makes this easy on any Eloquent model:

use Sensson\Mailchimp\Casts\MailchimpAuth;

protected $casts = [
    'mailchimp' => MailchimpAuth::class,
];

use Sensson\Mailchimp\Data\MailchimpToken;

$user->mailchimp = new MailchimpToken(accessToken: $token, serverPrefix: $dc);
$user->save();

Usage

use Sensson\Mailchimp\Facades\Mailchimp;

$mailchimp = Mailchimp::make($user->mailchimp->serverPrefix, $user->mailchimp->accessToken);

Audiences

$audiences = $mailchimp->audiences()->all();

$audience = $mailchimp->audiences()->get('list-id');

Members

use Sensson\Mailchimp\Data\Member;
use Sensson\Mailchimp\Enums\MemberStatus;

$members = $mailchimp->members('list-id')->all(count: 50, offset: 0);

$member = $mailchimp->members('list-id')->get($subscriberHash);

Create or update a member:

$member = new Member(
    email_address: 'john@example.com',
    status: MemberStatus::Subscribed,
    merge_fields: ['FNAME' => 'John', 'LNAME' => 'Doe'],
);

$mailchimp->members('list-id')->createOrUpdate($member);

Mailchimp blocks subscribing addresses that have previously unsubscribed, bounced, or been forgotten. These surface as typed exceptions so you can react without inspecting the response body:

use Sensson\Mailchimp\Exceptions\ForgottenEmailNotSubscribedException;
use Sensson\Mailchimp\Exceptions\MemberInComplianceStateException;

try {
    $mailchimp->members('list-id')->createOrUpdate($member);
} catch (MemberInComplianceStateException|ForgottenEmailNotSubscribedException) {
    // member is permanently unreachable — the contact must resubscribe themselves
}

Archive a member:

$hash = md5(strtolower('john@example.com'));

$mailchimp->members('list-id')->archive($hash);

Batch subscribe multiple members at once:

$members = [
    new Member(email_address: 'john@example.com', status: MemberStatus::Subscribed),
    new Member(email_address: 'jane@example.com', status: MemberStatus::Subscribed),
];

$mailchimp->members('list-id')->batch($members);

Tag and untag members:

$hash = md5(strtolower('john@example.com'));

$mailchimp->members('list-id')->tag($hash, ['VIP', 'Early Adopter']);
$mailchimp->members('list-id')->untag($hash, ['VIP']);

Merge Fields

$fields = $mailchimp->mergeFields('list-id')->all();

Webhooks

use Sensson\Mailchimp\Enums\WebhookEvent;
use Sensson\Mailchimp\Enums\WebhookSource;

$webhooks = $mailchimp->webhooks('list-id')->all();

$webhook = $mailchimp->webhooks('list-id')->create(
    'https://example.com/webhook',
    [WebhookEvent::Subscribe, WebhookEvent::Unsubscribe],
    [WebhookSource::User, WebhookSource::Admin],
);

$mailchimp->webhooks('list-id')->delete($webhook->id);

Testing

Use fake() and authFake() with Saloon's MockClient:

use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;
use Sensson\Mailchimp\Facades\Mailchimp;
use Sensson\Mailchimp\Requests\Audiences\ListAudiences;

$mock = new MockClient([
    ListAudiences::class => MockResponse::make([
        'lists' => [
            ['id' => 'abc123', 'name' => 'Newsletter', 'member_count' => 100],
        ],
    ]),
]);

Mailchimp::fake($mock);

$audiences = Mailchimp::audiences()->all();

$mock->assertSent(ListAudiences::class);

Run the test suite:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Sensson
• All Contributors

License

The MIT License (MIT). Please see License File for more information.