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,
];

$user->mailchimp = (object) ['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);

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

License

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

sensson / laravel-mailchimp

Maintainers

Details