Mailchimp Laravel Package

Getting Started

• composer require statamic-rad-pack/mailchimp, then publish the config (php artisan vendor:publish --tag=mailchimp-config — confirm the exact tag in the README for your version). Keep MAILCHIMP_API_KEY and the audience/list ID in .env so config:cache in production doesn't bake secrets into a tracked file.
• The API key must be the full key including the datacenter suffix (abc123...-us21). The client derives the base URL from that suffix, so a key with the wrong or missing -usXX produces confusing 404/401 responses that look like auth failures.
• Read, in order: the published config/mailchimp.php (credential and merge-field mapping), the addon's service provider (what's bound and what events fire), then the form integration itself — that's where merge-field mapping and the subscribe call happen.
• Fastest first use case: create a one-field newsletter form in resources/forms/ with an email field, point it at a throwaway sandbox audience, submit it from the front end, and confirm the member appears in Mailchimp. That single pass validates credentials, audience ID, merge-field mapping, and error surfacing all at once.
• Do that first run against a test audience, not your production list. There is no dry-run mode; submissions are real.

Implementation Patterns

• One form per audience, or one audience with groups. The simplest mental model is resources/forms/newsletter.yaml → one Mailchimp audience. If you need segmentation (product updates vs. events), prefer Mailchimp groups/interests on a single audience over multiple forms with duplicated validation logic.
• Map merge fields explicitly. Mailchimp merge tags (FNAME, LNAME, PHONE, custom tags) must already exist on the audience and be spelled exactly. Keep the field-handle → merge-tag mapping in config so a field rename in the form doesn't silently drop data.
• Always collect a consent checkbox and validate it server-side (accepted rule) for GDPR-adjacent jurisdictions. Statamic stores the submission, so you get an audit trail Mailchimp won't give you — store a timestamp and the consent text version alongside it.
• Wrap the subscribe call in a queued job or listener if you care about form latency or Mailchimp downtime. Statamic form submissions run synchronously in the request; a slow or failing API call delays the visitor's response. Listening to the form-submitted event and dispatching a job lets you fail open (visitor sees success, job retries) or fail closed (job failure surfaces an alert) as a deliberate choice.
• Treat "Member Exists" as success. Mailchimp returns a 400 with title: "Member Exists" for a duplicate email. Catch that specific case and log at info; otherwise your error dashboard lights up every time someone re-submixes the newsletter form.
• Respect double opt-in. If the audience has double opt-in enabled, the API returns status pending and Mailchimp sends the confirmation email. Don't build a UI that says "you're subscribed" — say "check your inbox to confirm."
• Multi-environment setup: point local and staging at a sandbox audience via .env, or gate the integration behind a config flag so seeding and QA runs never touch the real list.
• Testing: Http::fake() on the Mailchimp endpoints (https://<dc>.api.mailchimp.com/3.0/...) with fixture responses for 200, 400 Member Exists, and 500. Assert that a duplicate submission is handled as success and that an API error doesn't throw a 500 at the visitor.

Gotchas and Tips

• The v6.2.5 "audience pull max 500" is a control-panel concern, not a subscription limit. It caps how many audiences get pulled into the CP for selection. If you have more than 500 audiences on the account (rare), the picker truncates — this has nothing to do with how many members you can subscribe. Don't over-engineer around it.
• Required merge fields are the #1 silent breakage. If the audience marks FNAME required and your form doesn't collect it, every submission fails with a 400 that a visitor never sees. Turn off "required" in Mailchimp for anything the form doesn't send, or send a placeholder.
• Errors are easy to swallow. Statamic forms typically show a success state regardless of what a third-party integration does unless the addon explicitly throws. Log the Mailchimp response body at warning on non-2xx and set up an alert on that log channel — otherwise you discover a broken API key weeks later.
• Stale config after upgrades. After bumping the addon, run php artisan config:clear and queue:restart (if you've queued the integration). Most "the new behaviour didn't apply" reports are cached config or old workers.
• Rate limits are real on bulk work. Mailchimp allows roughly 10 concurrent requests with a small burst. If you're backfilling historical submissions into the audience, use the batch endpoint or throttle; a naive loop over thousands of Statamic\Facades\Form submissions will hit 429s.
• Don't edit vendor code to add tagging or grouping. Prefer a listener on the form-submitted event that calls the Mailchimp API directly for anything the addon doesn't expose (tags, interests, notes). That keeps upgrades to v6.x patch releases trivial.
• Pin the version in composer.json and re-run your fixture tests after upgrading — a patch bump that changes a request shape or a limit is cheap to catch in tests and expensive to catch in production. v6.2.5 itself is a patch with no migration work expected.
• Check the submission record, not just Mailchimp, when debugging. If the Statamic submission exists but the member doesn't, the failure is in the integration; if neither exists, it's validation in the form itself. That split narrows the problem in seconds.