Mailchimp Laravel Package

Getting Started

This is a Statamic addon, so the realistic starting point is a Statamic site that already has a form (newsletter signup, gated download, event registration) and wants those submissions landing in a Mailchimp audience automatically.

1. Install in the Statamic project (not a bare Laravel app): composer require silentz/mailchimp, then publish the config with php artisan vendor:publish and look for config/mailchimp.php.
2. Read the config file first. It is the most reliable "documentation" this package ships with. Expect an API key and an audience/list ID, both of which belong in .env (MAILCHIMP_API_KEY, MAILCHIMP_LIST_ID) rather than committed config.
3. Grab credentials from Mailchimp. The API key lives under Account → Extras → API keys, and you must note the datacenter suffix (-us1, -eu1, etc.) — the key format is <key>-<dc> and the addon derives the API endpoint from it.
4. First use case: a Statamic form handler. Point one existing Statamic form at the addon and submit it once. Watch storage/logs/laravel.log and the Mailchimp audience in parallel — the fastest way to confirm the wiring is a real submission showing up as a new member.

If you need programmatic subscription outside a form (a custom controller, a Livewire component, an Artisan command backfilling old signups), resolve the package's service from the container or use whatever facade it exposes and call its subscribe method directly.

Implementation Patterns

Form-driven subscription (the common path). Register the addon as a handler/action on your Statamic form, so every submission is mirrored to Mailchimp. This keeps marketing logic out of your controllers and lets non-developers edit the form in the Control Panel. Map form field handles to Mailchimp merge tags (typically FNAME, LNAME, EMAIL) either in config or in the form definition, depending on how the addon is wired.

Programmatic subscribe in a listener or controller. For cases where the form isn't the source of truth — user registration, checkout completion, a "notify me" modal — call the package directly after your own validation, then treat Mailchimp as a best-effort side effect (see Gotchas). This is the pattern that scales: one small SubscribeToNewsletter action class, injected wherever needed.

Multiple audiences. If you segment by product, region, or lead source, prefer a config map of named audiences (newsletter, customers, waitlist) over hardcoding a single list ID. Most Mailchimp addons let you pass the list ID per call; wrap that in your own service so swapping a list later is a config change, not a grep.

Group and tag assignment. Use Mailchimp interest groups/tags for segmentation instead of maintaining parallel lists. Push the group/tag alongside the subscription so your marketing team can slice audiences without engineering work.

Queue the call. Wrap the subscription in a queued job (or Mailchimp::queue(...) if the addon offers it). Mailchimp round-trips add 100–400ms and you don't want that in a form POST. Pair with retry() and a low tries count so a Mailchimp outage doesn't flood the queue with dead jobs.

Sync existing Statamic users. A scheduled Artisan command that iterates User::all() and upserts members is a common one-off. Batch it in chunks and respect rate limits (see below) — do not foreach thousands of users synchronously.

Gotchas and Tips

• The API key's datacenter suffix is load-bearing. abc123-us1 means all requests go to us1.api.mailchimp.com. A truncated or copied key without the suffix produces confusing 401s rather than a clear "wrong endpoint" error.
• Mailchimp renamed "Lists" to "Audiences." Old docs, old Stack Overflow answers, and possibly this addon's own config keys still say list_id. They mean the same thing; the audience ID is a short hex string found in Settings → Audience name and defaults.
• Double opt-in is an audience setting, not an API flag. If new members land as pending rather than subscribed, look at the audience's "Form settings" in Mailchimp before blaming the addon. This is the single most common "it doesn't work" report.
• Never let Mailchimp failure break the user-facing flow. Wrap subscribe calls in try/catch, log the error, and still return success for the form. A Mailchimp 500 or a duplicate-email 400 should be invisible to the person signing up.
• Duplicate emails return an error, not a no-op. Mailchimp responds with a 400 and a Member Exists title. Decide explicitly whether to treat that as success (idempotent upsert semantics) or to PATCH the existing member — the addon may or may not handle this for you.
• Merge tags are uppercase and must exist. Sending FNAME when the audience only has FIRSTNAME fails or silently drops data depending on your error handling. Create merge fields in Mailchimp first, then wire them up.
• Rate limits are per-account. Roughly 10 requests/second on most endpoints, with stricter concurrency on batch operations. Any backfill or user-sync loop needs usleep() or a rate-limited job — this is where naive integrations fall over.
• Testing. Mailchimp has no true sandbox, so use a dedicated test audience and a separate API key in .env.testing, and guard against accidentally writing to production by asserting the audience ID in tests.
• Low-traffic package, so verify compatibility. With a small star count and no dependents, check the addon's Statamic version constraint against your composer.json before assuming it works on the latest Statamic/Laravel. If a form handler misbehaves after an upgrade, the package's service provider and form-action registration are the first places to inspect.
• Extension point: your own wrapper. Because the addon's surface area is small, wrap it in an app-level Newsletter service. That gives you one place to swap in a queued job, add logging, or replace the dependency entirely if you outgrow it — without touching every call site.