Statamic Acumbamail Laravel Package

Getting Started

1. Install the addon in a Statamic 5 project. Confirm your stack first: Statamic 5, Laravel 11/12, PHP 8.2+. Anything older (Statamic 4 / Laravel 10) is outside the support matrix for this release.

   composer require <vendor>/statamic-acumbamail
   php please vendor:publish --tag=acumbamail-config
   

2. Authenticate. Add your Acumbamail API credentials to .env and reference them from the published config. Do this before touching the CP — the listing screens will fail or show empty states without a working connection.
3. Look here first, in this order:
   • The published config file (credentials, defaults, edition-related keys).
   • The CP area — the addon ships listing, editing, and site configuration screens. That's your source of truth for which lists and merge fields the addon actually sees.
   • Your resources/forms/ YAML — form configuration is where email/consent/list selection is wired up.
4. First use case: build the smallest possible newsletter signup. One form, one email field, one required consent checkbox, one Acumbamail list, double opt-in enabled. Submit it, then verify the contact exists in Acumbamail in pending/unconfirmed state rather than assuming success. That single loop exercises the API client, the config, the merge mapping, and the opt-in path at once.

Start on the Free edition to validate the integration, then decide whether Lite (merge field mapping) or Pro (multi-site) is genuinely needed.

Implementation Patterns

Form-as-configuration, not form-as-code. The addon's model is that a Statamic form maps to an Acumbamail list. Keep the mapping declarative in the form YAML and let editors change list selection in the CP rather than shipping deploys for a list change.

Merge field mapping (Lite/Pro). Map Statamic field handles to Acumbamail merge tags explicitly — do not rely on name coincidence. A typical mapping:

acumbamail:
  list_id: "12345"
  double_opt_in: true
  merge_fields:
    email: email
    nombre: first_name
    apellidos: last_name

Treat this map as the contract between your form and the external schema. Keep it in version control and review it whenever someone edits the form in the CP.

Separate consent capture from subscription. The addon handles the subscribe call; it does not necessarily give you a durable, exportable consent record. Write your own submission record (timestamp, form handle, site, IP, consent text version, and the Acumbamail response/pending status) so you can prove consent later. This is cheap at build time and expensive to retrofit.

Queue the outbound call. Wrap the subscribe in a queued job or at minimum a try/catch. An Acumbamail timeout should not lose the submission or show a 500 to the visitor. Persist the submission locally, dispatch, and retry with backoff on 429/5xx.

Double opt-in is asynchronous by design. Never render "You're subscribed" after submit. The honest states are pending confirmation and already subscribed. Design your confirmation template and your post-submit message around that, and make sure re-submitting an already-pending address doesn't error visibly.

Multi-site (Pro). Configure list and merge mapping per site rather than globally. Sites with different languages or brands should have distinct lists and distinct consent wording. Verify that a submission on site B never falls back to site A's list when B's config is incomplete — that failure mode is silent and pollutes your audience.

Edition boundaries as a design constraint. Free = core subscribe. Lite/Pro = merge mapping. Pro = multi-site. Write your integration code so that a Free install degrades gracefully (fields simply not mapped) rather than throwing on a missing config key. That keeps the upgrade path open without a refactor.

Gotchas and Tips

• Edition gating is the most likely source of confusion. Multi-site keys simply won't exist on Free/Lite. Guard config reads, and document in your project README which edition you're on and why.
• Merge field name mismatches fail on the wrong side. A wrong tag usually surfaces as a rejected request or a silently dropped value in Acumbamail, not as a Statamic error. Log the outbound payload in non-production and diff it against the Acumbamail list definition when a field "doesn't save."
• Verify the double opt-in confirmation flow end-to-end with a real inbox before launch. The confirmation email, the redirect target, and the "already confirmed" behaviour are all provided by Acumbamail, not by your app — test them in the actual list, not a sandbox list with different settings.
• Config caching. After publishing or editing config, run php please stache:clear / php artisan config:clear as appropriate. Stale config after an edition or credential change looks exactly like a broken API key.
• Don't assume Http::fake() covers it. If the addon wraps its own HTTP client, your tests need to fake the underlying binding, not Laravel's facade. Check the service provider bindings before writing integration tests.
• Consent is your problem, not the addon's. Store consent proof alongside the submission. If the addon's data model doesn't have a field for it, add it in your own submission handler or a listener rather than relying on Acumbamail's record.
• Extension points to check early: any events emitted around subscribe/confirm, and whether the CP site configuration is overridable via config file. If events exist, hook consent logging and error reporting there rather than forking templates.
• Pin the version. v1.0.0 is an initial release; the config schema and merge-mapping format are the most likely things to shift. Constrain to ^1.0 and read changelogs before minor bumps in the first few releases.