Filament Audience Sync Laravel Package

Product Decisions This Supports

• Build vs. buy for audience/email-marketing sync: shipping a first-party Mailchimp/Brevo integration typically costs 2–6 engineer-weeks (OAuth/API keys, field mapping, tag sync, double opt-in, 429 backoff, consent state, UI). This package (MIT, free) collapses that to an install plus model/resource wiring — a strong default for teams whose differentiation is not "we wrote a Mailchimp client."
• Roadmap sequencing for admin panels: enables a "subscriber lifecycle" slice — status column (Subscribed / Pending confirmation / Unsubscribed / Cleaned / Archived / Not subscribed), record actions, and queued bulk actions — without blocking on a dedicated integrations epic. Good candidate for a thin MVP release, then iterate.
• Feature scope decisions: the presence of a status table (no per-row API call), cached dashboard widgets, and failure-reason flagging means you can commit to admin-facing observability (members, unsubscribes, open/click rates, recent campaigns) in the same release rather than deferring it.
• Provider strategy / portability: the AudienceSync driver contract plus extend() makes provider choice a configuration decision rather than an architecture one. Supports a "start with one ESP, add MailerLite/Kit/custom later" roadmap with bounded cost. Conversely, if you need a provider not yet shipped, budget for a driver build (the contract reduces, not eliminates, that work).
• Compliance and consent positioning: "consent first" behavior — never re-subscribing anyone unsubscribed, bounced, or archived, in provider or panel — plus GDPR notes in the README is a decision-level asset. It lets you accept marketing/compliance review earlier and reduces the risk of a re-subscription incident becoming a support or legal issue.
• Operational decisions: queued, chunked bulk actions with retries, Retry-After + exponential backoff on 429/5xx/connection errors, .env-only API keys, and redaction of keys from every error map directly to on-call burden and security review scope — use these as the acceptance criteria in your own release checklist.
• Platform baseline decisions: constrains you to PHP 8.2–8.5, Laravel 12/13, Filament 4/5. If your panel is on Filament 3 or Laravel 11, this package is a forcing function on an upgrade decision — price that in before committing.
• Explicit non-decision: it does not yet support a validated live-provider claim. Treat "run against a real Mailchimp/Brevo account" as a launch gate you own, not something the package has de-risked for you.

When to Consider This Package

Adopt when most of the following hold:

• You run a Filament 4 or 5 admin panel on Laravel 12/13, PHP 8.2–8.5, and the audience you manage maps to a resource whose model can implement Subscribable.
• Your ESP is Mailchimp or Brevo, or you are willing to write a driver against the provided contract for MailerLite, Kit, or an in-house provider.
• You want record-level and bulk subscribe/sync/edit-tags/unsubscribe from inside the panel, plus a local status table so list views don't hammer the provider API.
• Consent enforcement is a requirement, not a nice-to-have — you need a guarantee that unsubscribed/bounced/archived contacts are never re-subscribed.
• You want dashboard-level audience metrics (members, unsubscribes, open/click rates, recent campaigns) with caching, and are comfortable that these are provider-derived and eventually consistent.
• You value queued, retry-safe bulk operations with rate-limit handling and secret redaction out of the box, over a bespoke integration you'd have to harden yourself.

Look elsewhere, or plan to invest, when:

• You need production-proven provider behavior. The provider evidence is fixture-based — automated tests use response fixtures built from documented Mailchimp/Brevo API shapes via Laravel's HTTP fake, and the real-UI pass ran against a stateful fake. It has not been run against a live Mailchimp or Brevo account. If a live-account validation sprint isn't in your budget, this is a material risk (silent field-mapping drift, real-world rate-limit shapes, double opt-in edge cases).
• You're on Filament 3 / Laravel 11 / PHP 8.1 — no supported path.
• You need providers beyond Mailchimp/Brevo today and cannot absorb driver development.
• You need rich automation — journeys, segmentation logic, send-time optimization, A/B testing, transactional email. This is audience sync, not a campaign platform.
• You require SSO/SCIM, audit logging, multi-tenant provider credentials, or per-tenant rate-limit isolation — none of that is claimed here.
• You cannot own the compliance surface yourself. GDPR notes in the README are documentation, not a DPA, sub-processor register, or data-retention implementation. Your legal review still applies.
• You need vendor support/SLA. MIT community package, explicitly unaffiliated with Mailchimp, Brevo, Kit, MailerLite, or Laravel — no support contract, no indemnity.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a free, MIT-licensed Laravel/Filament package that gives our admin panel a complete email-audience sync — subscribe/unsubscribe, field and tag sync, bulk queued operations, a subscriber status view, and cached audience dashboards — for Mailchimp and Brevo. It replaces what would otherwise be several engineer-weeks of integration and hardening work (rate-limit backoff, retries, secret redaction, consent enforcement) with an install and a short configuration step. The main caveat to fund: it has been verified against API fixtures and a simulated provider, not a live Mailchimp or Brevo account, so we should budget a short live-account validation before we put customer data through it.

To engineering: Scope is small and well-bounded. Composer install, publish + run migrations, register AudienceSyncPlugin::make() on the panel, implement Subscribable on the target model (trait provides defaults), set API keys in .env. Drivers exist for Mailchimp (merge fields, tags, double opt-in) and Brevo (attributes, lists); AudienceSync::extend() covers anything else. Status is served from a local table so list views don't fan out API calls, and failures are surfaced with a reason. CI covers PHP 8.2–8.5 × Laravel 12/13 × Filament 4/5 with Pint, PHPStan, and 70 Pest tests.

To engineering — the honest risk list:

1. No live-provider run. All provider testing is fixture/fake-based. Assign an owner and a real sandbox account per provider as a launch gate; verify merge-field and attribute mapping, double opt-in flow, tag semantics, and 429/5xx behavior against the real API.
2. Fixture drift. Documented API shapes diverge from production over time; add a scheduled contract check or a thin live smoke test in CI.
3. Driver scope. Additional providers are our cost, not the package's.
4. Compliance is shared. Consent-first logic is implemented and GDPR notes exist, but DPAs, retention, and lawful basis remain ours.

To compliance/legal: The package is consent-first by design — anyone unsubscribed, bounced, or archived in the provider or in our panel is never re-subscribed — and ships GDPR notes. API keys live in .env and are redacted from every error message. It is MIT-licensed and unaffiliated with any ESP or with Laravel; we still own the data-processing agreements and retention policy.

Recommendation: Adopt for a bounded pilot behind a feature flag on one panel and one provider, with live-account validation and a mapping review as exit criteria. Reassess to "standard" once the live pass is green; keep the driver abstraction as the hedge against provider changes.