Campaign Monitor Laravel Package

Getting Started

• Install with composer require statamic-rad-pack/campaign-monitor, then publish the config: php artisan vendor:publish --tag=campaign-monitor-config. Add your Campaign Monitor API key and client ID to .env and reference them from config/campaign-monitor.php.
• Read in this order: the config file (credentials, default list, custom-field map), the service provider (what it registers — Antlers tags, form handlers, fieldtypes, and any CP nav entries), then the fieldtype so you know what value it stores (a list ID) versus what it renders.
• First use case: create a Statamic form with an email field, enable the Campaign Monitor form submission handler in the form's settings, point it at a list, and submit a test entry. Confirm the subscriber appears in Campaign Monitor before wiring up custom fields or the user-registration flow. This single path — form → handler → list — is the core of everything else.

Implementation Patterns

• Form handler, not custom controllers. The package ships a form submission handler for Statamic forms; enable it per-form and let it own the API call. Hand-rolling a listener means reimplementing custom-field mapping, error handling, and consent logic the addon already gives you.
• Fieldtype-driven list selection. Use the provided fieldtype on your forms/blueprints so editors pick the mailing list from the control panel rather than hardcoding list IDs in templates or config. Treat the stored value as an opaque ID and resolve it through the addon at submit time.
• Antlers tags for frontend lists and signup. Use the tag (e.g. {{ campaign_monitor:lists }} and the subscribe-style tag) for lightweight embeds like footers and sidebars. Keep them thin — one tag call per block, output-cached — so a slow Campaign Monitor API never sits in your render path.
• Custom field mapping in config. Map Statamic field handles to Campaign Monitor custom field keys in the config file. Do the mapping once, centrally; do not scatter merge_fields logic across forms and templates.
• User registration sync. Hook the addon into Statamic's user registration flow to subscribe new users to a default list, and decide explicitly whether profile edits should update the subscriber. Update/subscribe is idempotent on the API side, so re-syncing is safe — but only if you map fields consistently.
• Test at the submission boundary. Feature-test that submitting a form calls the handler with the expected subscriber payload (fake the HTTP client), and one live smoke test per deployment against a non-production list. Live API calls are the only thing that reliably catches credential/field-name drift.
• Async where possible. For higher-traffic forms, queue the subscription (the addon's handler can be wrapped in a queued job or notification) so a Campaign Monitor outage or slow response doesn't fail the user's form submission.

Gotchas and Tips

• Custom fields must exist in Campaign Monitor first. Mapping a Statamic field to a CM custom key that doesn't exist on the list fails silently or drops the field. Create the custom fields in the CM UI before deploying the map.
• Double opt-in vs. immediate subscribe. Campaign Monitor lists have their own confirmation settings. If subscribers aren't appearing as "active", check the list's opt-in config before blaming the addon — and be aware that "subscribed" locally may still mean "unconfirmed" upstream.
• Existing subscribers. Subscribing an email that already exists can update the record or be a no-op depending on list settings. If you need to update custom fields for existing subscribers, verify the addon sends the update path rather than erroring on "already subscribed".
• Consent and GDPR. A newsletter subscription needs explicit consent captured at submit time. Store the consent flag/timestamp on your Statamic entry (or form submission) so it survives independently of the Campaign Monitor record.
• Cache the Antlers tags. Tags that hit the API on every render will tank page performance and burn rate limits. Wrap list-rendering tags in Statamic's cache tags or a short TTL, and clear that cache when lists change.
• List IDs are brittle. If an editor deletes or re-creates a list in Campaign Monitor, any stored list ID field value goes stale. Validate that the ID still resolves before submitting, and fail softly (log, don't 500) if it doesn't.
• Config caching in production. Credentials live in config, so php artisan config:clear / config:cache on deploy is mandatory after any .env or config edit. "It works locally but not in prod" is almost always stale config cache or a missing env var.
• Debug the API response, not the template. When a subscriber doesn't sync, dump the API response body (or log it) before touching the form markup. The addon's error surface is thin; a wrong API key and a wrong list ID look nearly identical from the frontend.
• Extension points. The service provider is where the Campaign Monitor client and handlers are bound; swap or subclass the client there rather than editing the published config, so composer update stays clean. Check the release notes (v3.0.1 fixed blueprint layouts under Statamic v6) and keep the addon version aligned with your Statamic major — fieldtype and blueprint handling have shifted across majors.