Mailerlite Laravel Package

Getting Started

• Install with composer require siterig/statamic-mailerlite, then publish the addon config (php artisan vendor:publish --tag="statamic-mailerlite-config" — confirm the exact tag in the README, since addons vary between -config and provider-scoped tags).
• Add your credentials to .env before touching anything else. MailerLite's current API uses a Bearer token, not the legacy v1 API key, so generate the token under Integrations → API in the MailerLite dashboard and set it as the addon's configured env key (typically MAILERLITE_API_KEY / MAILERLITE_TOKEN depending on how v2.x names it).
• Look first at, in order: config/statamic-mailerlite.php (key names, default group, caching), the addon's ServiceProvider (what it binds and registers), and the README's usage section. v2.0.0 was the API-v2 rewrite and v2.0.1 only touches dependencies/docs, so the README is the authoritative source for the current surface.
• Fastest first use case: a newsletter signup on a Statamic form. Create the form, add an email field, point the addon at a MailerLite group ID, and submit. Verify the subscriber appears in MailerLite before building anything else — this exercises the token, the group ID, and the field mapping in one shot.
• If you're coming from a 1.x install, treat this as a fresh setup rather than an upgrade: re-publish the config and re-enter credentials, because the token format and group identifiers changed with the v2 API.

Implementation Patterns

• Form submission hook: the primary day-to-day pattern is listening for Statamic's SubmissionCreated event (or using the addon's built-in form integration if it ships one) and pushing the submission into MailerLite. Map Statamic form field handles to MailerLite field keys explicitly in config or in the listener — don't rely on identical naming.
• Always queue the API call. A MailerLite round-trip inside the request cycle makes form submissions slow and turns a MailerLite outage into a broken contact form. Dispatch a job from the listener, and let the submission succeed regardless of the API result.
• Antlers tags for read paths: if the addon exposes tags for listing groups or subscriber counts, cache the output. Group lists change a few times a year; wrap them in {{ cache }} or a Cache::remember call with a long TTL rather than hitting the API per page render.
• Group selection in the Control Panel: for editor-facing setups, expose the target group as a blueprint field (a select populated from the API, or a plain config value per form). Keep the API token server-side — never in a blueprint default or a frontend-rendered select.
• Multi-site: bind group IDs per site in config rather than globally, so a German and an English newsletter land in different groups while sharing one token.
• Programmatic use: resolve the client out of the container (or the addon's facade, if provided) in your own actions and commands — e.g. a nightly Artisan command syncing members, or a user-registration listener that adds new accounts to an onboarding group. Keep a thin wrapper class of your own around it so a future addon major doesn't ripple through the codebase.
• Testing: Http::fake() against connect.mailerlite.com/* and assert the outbound payload. This is also the cheapest way to confirm field mapping, since MailerLite's error responses for unknown fields are easy to miss in manual testing.

Gotchas and Tips

• v2.0.1 is a patch, not a migration. The changes are dependency/vulnerability fixes plus docs — no breaking API changes relative to v2.0.0. Upgrade is still recommended because of the security fixes. The breaking change lives one release back: v2.0.0 moved to the MailerLite v2 API, which renamed config keys, switched to Bearer tokens, and uses string group IDs instead of the old integer IDs.
• Re-publish the config after upgrading. Merged addon config with stale keys is the most common cause of "it silently does nothing" — the addon reads a key that still holds a v1 value. Run php artisan config:clear (and re-run config:cache in production) after any .env or config edit.
• Legacy API keys fail with 401s. If you see authentication errors with a key that "definitely works" in the MailerLite UI, you're almost certainly using a v1 key. Generate a v2 token.
• Watch the rate limit. MailerLite throttles around 120 requests/minute; batch imports and syncs will hit 429s. Use chunked jobs with exponential backoff ($backoff on the job), and never retry in a tight loop — repeated 429s can get you temporarily blocked.
• Double opt-in is a group setting, not a code setting. Subscribing via the API won't necessarily send a confirmation email unless the group is configured for it. Don't assume the API call alone produces the double opt-in flow your client expects.
• Custom fields must exist in MailerLite first. Pushing an unknown field either errors or is silently dropped depending on the endpoint. Create fields in MailerLite (or via a one-off command) before wiring them into form mapping.
• Decide deliberately on duplicate handling. Re-subscribing an existing address may return the existing record or a conflict depending on the endpoint used; if you're syncing, prefer upsert semantics and make the job idempotent so retries don't create noise.
• Redact the token in logs. Enable debug logging while integrating, but scrub the Authorization header — Laravel's HTTP client logs and exception messages will otherwise leak credentials into your log files.
• Extension points: publish the addon's views to restyle any CP or tag output, bind your own client implementation over the addon's binding if you need custom retry/timeout behaviour, and prefer your own listener over editing vendor files so addon updates stay clean.
• Check the Statamic/Laravel constraint before upgrading. Statamic 5 pins Laravel 11+, so a Laravel 10 app stays on the older Statamic line — read composer.json in the tag before running composer update on a mixed-version project.