naif/mailchimp-tool
A Laravel package for integrating Mailchimp into PHP applications, offering convenient tools for managing lists, subscribers, and email marketing workflows through a framework-friendly API.
This is a Laravel Nova tool (admin panel), not a general-purpose Mailchimp client. You need Laravel Nova installed first — the tool is useless without it.
Minimal path:
xxxxx-us1, note the datacenter suffix)composer require naif/mailchimp-tool
publishes()):
php artisan vendor:publish --provider="Naif\MailchimpTool\ToolServiceProvider"
.env:
MAILCHIMP_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxx-us1
MAILCHIMP_LIST_ID=abc123def4
app/Providers/NovaServiceProvider.php:
public function tools()
{
return [
new \Naif\MailchimpTool\MailchimpTool(),
];
}
php artisan optimize:clear then load /nova — the tool appears in the left sidebar.Where to look first:
src/MailchimpTool.php — the boot()/renderNavigation() and route registration; this tells you which HTTP endpoints the Vue UI calls.resources/js/tool.js (or components/) — reveals form fields and API calls. If only dist/js/tool.js exists (compiled), grep it for endpoint strings.config/ — key, list ID, and any default segments/tags.routes/api.php — the backend proxy to Mailchimp.First use case: log into Nova, open the tool, and use it to (a) look up an existing subscriber and toggle their status, or (b) send a one-off campaign to a saved segment. Start by reading a subscriber you created manually in Mailchimp's own UI — that verifies API key, list ID, and datacenter routing all at once before you touch write operations.
Treat it as an admin console, not a sync layer. The package is for human-driven actions (add/edit subscriber, send campaign). If you need Mailchimp data in your app (e.g., "is this user subscribed?"), don't route it through this tool — use the Mailchimp API directly or a maintained SDK, and keep this tool purely for the Nova sidebar.
Pair it with a model observer for the actual subscription logic. A common pattern:
// app/Observers/UserObserver.php
public function created(User $user)
{
Mailchimp::lists()->addMember($listId, [
'email_address' => $user->email,
'status' => 'subscribed',
'merge_fields' => ['FNAME' => $user->first_name],
]);
}
Then use the Nova tool only to fix up edge cases (bounced, unsubscribed, wrong email) that ops staff handle by hand. This avoids coupling your registration flow to whatever API wrapper the tool bundles.
Multi-list / segment configuration. If the tool reads a single list_id from config, you can extend it by publishing the config and pointing list_id per-environment. For per-tenant lists, either fork MailchimpTool to resolve the list ID from the request/tenant, or wrap a thin custom Nova tool around the same Mailchimp endpoints — forking is usually cleaner than trying to bend this one.
Campaign sending belongs in a queued job. The tool's "send email" button likely fires synchronously through the Nova request. For anything larger than a small test segment, wrap your real sends in a job:
SendMailchimpCampaign::dispatch($campaignId)->onQueue('mailchimp');
Respect Mailchimp's ~10 concurrent / burst limits; the package almost certainly doesn't implement backoff.
Use Nova's toast/error surface. When an API call fails (invalid email, duplicate member, rate limit 429), the tool should bubble the Mailchimp error body up. If it silently swallows errors, that's your first patch — you need the title/detail from the v3 response to debug.
Environment separation. Mailchimp keys are per-account; use separate accounts (or at minimum separate lists) for staging and production. Never point a staging app at the production list ID.
each()). Test in a throwaway environment first.laravel/nova: * and break silently between majors. The compiled Vue bundle in dist/js/ targets whatever Nova 1.x/2.x shipped. It will likely not render correctly on Nova 4+ without rebuilding the frontend. Check composer.json and dist/ before assuming it works.-us1 must call https://us1.api.mailchimp.com/3.0/.... If you see 404 for valid-looking resources, the datacenter is being stripped or hardcoded wrong.MAILCHIMP_LIST_ID in .env won't take effect with cached config — always php artisan config:clear on the server during debugging.resources/js has been edited, run npm install && npm run production (or prod per its package.json) and re-copy the built file. Nova won't rebuild it for you.debug config flag, then tail -f storage/logs/laravel.log. Mailchimp returns useful {type, title, status, detail, instance} payloads — log the full body, not just the status code.400) are common when adding by email. Normalize to lowercase, and catch "Member Exists" before treating it as a failure — use PUT /lists/{id}/members/{md5(email)} for idempotent upserts.mailchimp/mailchimp_marketing) will be less work than patching a 2018 codebase for Nova 4.How can I help you explore Laravel packages today?