Statamic Marketing Laravel Package

Getting Started

This package sits in the outgoing-mail path: it rewrites links in rendered mail so clicks route through your app, records the hit, then redirects to the original destination. v2.39.2 is a patch that tightens URL matching in that redirector — nothing to configure, but read it before you debug "why is my magic link dead."

1. Install and publish config: composer require <vendor>/<package> then php artisan vendor:publish --tag=<package>-config. The config file is the whole surface area — read it top to bottom before touching code.
2. Run the migrations if the package ships tables (click/visit records). Check database/migrations in the package before assuming it's stateless.
3. Register the middleware or mail transport hook exactly as the README prescribes. Most breakage at this stage is a middleware that isn't in the right group, so links get rewritten but the redirect route 404s.
4. Send one mail to yourself with MAIL_MAILER=log, grep the raw output for a rewritten URL, then click it in a browser. That round trip is your smoke test.

First real use case: an onboarding or transactional email with two or three links. Confirm the redirect works, the click is recorded, and — critically — that any login/password-reset link is not wrapped. That last check is the one that bites.

Where to look first, in order: the config file, the redirect controller/route the package registers, the listener or middleware that performs the rewrite, and the changelog (the release notes explicitly point there, and for a .2 patch the changelog entry will say more than the summary does).

Implementation Patterns

Wrap at the mailer boundary, not in Blade. Let the package rewrite rendered output rather than hand-writing tracked URLs in templates. Hand-built tracked URLs rot the moment the package changes its route or signing scheme, and you lose the guarantee that exclusions are applied consistently.

Maintain an explicit exclusion list. Login, magic-link, unsubscribe, and one-time-token URLs must never be wrapped — a tracked redirect is an extra hop that some clients prefetch, and prefetching a single-use token burns it. Keep these in config, not scattered across templates.

Test against the URL shapes you actually generate. v2.39.2 exists because percent-encoded paths (%2F, %20, and friends) were being missed by the exclusion matcher. Anything that builds links with urlencode() or passes a signed URL through a query parameter is exposed. Add a test that asserts your password-reset link survives mail rendering untracked, including a variant with an encoded path segment.

Decouple recording from the redirect. If the package records clicks synchronously in the request that handles the redirect, a slow DB write becomes a slow user-visible redirect. Check whether recording is queued; if not, wrap the listener or use dispatchAfterResponse-style patterns so the redirect fires first.

In multi-tenant or multi-domain apps, verify how the package builds the tracking host. Hardcoding one host means links in mails sent from a secondary domain point somewhere unexpected — and some spam filters notice the mismatch.

Treat click data as analytics with a retention question. Click rows grow fast. Decide early whether you're keeping them, aggregating them, or pruning on a schedule; retrofitting that after a year of rows is unpleasant.

Gotchas and Tips

The login-link fix is the headline gotcha. Percent-encoded paths were previously not recognised as excluded, so a magic-link URL containing an encoded segment could be rewritten into a tracked redirect. If you skipped this patch, upgrade. If you're on it, still write the regression test — the matcher's exact normalisation rules are the kind of thing that regresses quietly in a future refactor.

Normalise before you compare. When adding your own exclusions, remember that /login/reset and /login%2Freset are the same path to a router and different strings to a naive matcher. Test both forms.

Prefetching and scanners will pollute your click data. Corporate mail scanners and link previews fire GETs on every URL in a message. Your open/click numbers will be inflated, and any single-use link will be consumed. This is why exclusions matter more than the analytics.

Debugging checklist when a link misbehaves: (a) is the middleware active on the redirect route, (b) does the rewritten URL appear in the raw MIME (MAIL_MAILER=log), (c) does the redirect route resolve in php artisan route:list, (d) does the destination survive a manual curl -I. That isolates rewrite vs. redirect vs. destination in four steps.

Config caching. After editing the package config, php artisan config:clear — a stale cached config is the most common reason a change "didn't take" in a deployed environment.

Extension points worth knowing: the exclusion/matching logic (the thing this patch touched) is usually the most valuable seam to override; the redirect controller is the second if you need custom 404/410 behaviour; events emitted on click are the third if you're piping into your own analytics. Prefer config over subclassing where both exist — you'll get patch releases for free.

Watch the changelog on .x bumps. This package moves in small increments; a v2.40 minor is more likely to carry a behaviour change in matching or rewriting than a .2 patch does. Pin the version in composer.json and upgrade deliberately rather than floating.