feat(mail): first-week onboarding tip sequence (dark-shipped)

[edwh]

What

A first-week onboarding email sequence for new members: one short, friendly tip a day for the first five days, following the welcome mail. It sets the expectation up front ("one short tip a day for five days"), teaches the handful of things that make Freegle click, and is signed off by a real local volunteer wherever we can find one. Dark by default so it ships safely ahead of any rollout, and carries the tracking/experiment machinery so its effectiveness is measurable in the sysadmin dashboard.

Internally this still lives under the reengage name (table, service, effectiveness dashboard) - the sequencing, tracking and experiment plumbing are identical; only the trigger and content changed from the earlier lapsed-user idea.

The five tips

Day	Tip	CTA
1	Welcome - and what makes a good offer. Sets the expectation, then: clear title, a photo, honest condition, roughly where you are.	Offer something
2	The stuff you think nobody wants. The half-tin of paint, odd cables, outgrown clothes languishing in cupboards and drawers - don't assume nobody would want it. On Freegle they nearly always do.	Offer something
3	Need something? Just ask. Freegle is for getting too - post a wanted; say what you're after, a line of why, roughly where; stay open on brand/condition.	Post a wanted
4	You can search for things. Type in what you need and see what's already been offered nearby; save a search so the right one doesn't pass you by.	Search Freegle
5	You're a freegler now. Quick recap + being a good neighbour (reply promptly, easy doorstep pickup, say thanks).	See what's near you

One shared MJML tip template (head/footer partials, plain-text alternative, RFC 8058 one-click List-Unsubscribe, a single clear CTA and a progress indicator), driven by per-day copy in ReengageContentService.

Rendered (headless Chrome, GPU off - sample data)

Day 1	Day 2	Day 3	Day 4	Day 5

Who gets it

• New members only - keyed off account age (users.added); tip N lands on day start_day + (N-1)*gap (days 1-5 by default). A safety bound (max_start_days) means first-enabling the feature can't back-blast everyone who joined last month.
• TrashNothing and LoveJunk accounts are excluded - they onboard through their own platform (SQL tnuserid/ljuserid/domain gate plus a belt-and-braces isTN()/isLJ() check).
• Plus the usual gates: genuine approved Freegle membership, not bouncing, not on holiday, marketing opt-out and per-group engagement opt-out honoured.

The volunteer sign-off

Every tip is signed by a real local volunteer where one exists, resolved exactly like the birthday-appeal sign-off so the two stay consistent:

• only communities the member genuinely joined - collection = Approved, rippled = 0 so a Rippling-Out auto-join can never appear to "come from" a group they never knowingly joined;
• nearest first (haversine on the group centroid vs the member's location), so it feels local rather than from the far side of the country;
• the volunteer must be an active, publicly-shown (users.settings.showmod) Moderator/Owner.

No such volunteer? It falls back to the plain "The Freegle team" voice rather than inventing one.

Instrumentation & experiment

Unchanged from the existing plumbing and still dark by default (rollout_pct = 0): every send records a stable arm (control/a/b), a journey segment, and an email_tracking id, so opens/clicks and whether a tip drove a real action (login/reply/post in the outcome window) are graphable per tip/arm/segment in the sysadmin Reengage effectiveness panel. mail:reengage-outcomes writes the outcomes; the control arm is a true holdout for measuring lift.

Roll-out

Inert until both knobs are opened: FREEGLE_REENGAGE_ALLOWLIST (empty = nobody; * = everyone; or specific pilot addresses) and "Reengage" in FREEGLE_MAIL_ENABLED_TYPES. Preview any/all tips into mailpit with php artisan mail:reengage --preview=you@example.com (bypasses the gates).

Tests

ReengageMailRenderTest (tip template + volunteer sign-off + fallback + escaping + full MJML compile), ReengageEmailsCommandTest (new-member trigger, TN/LJ exclusion, daily cadence, completion, dark-ship gates, dry run) and ReengageExperimentTest (deterministic bucketing, per-day subjects). Full iznik-batch Laravel suite green.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for golden-caramel-d2c3a7 canceled.

Name	Link
🔨 Latest commit	2bec8ed
🔍 Latest deploy log	https://app.netlify.com/projects/golden-caramel-d2c3a7/deploys/6a556610b79dcc00088e3aaa

[edwh]

Adversarial review + UI review — re-engagement sequence

Reviewed the core logic, mail rendering/security, tests, instrumentation, and experiment-readiness (four focused passes), and viewed the rendered stages in mailpit/headless-Chrome. The feature is well-built and correctly dark-shipped; the items below are what to fix before ramping, plus the effectiveness/experiment work now being added on top.

🔴 Blockers (before enabling for real users)

1. Double-mails the same lapse as mail:engage. The design says the sequence "finishes before the engage sunset so the two never double-mail." That's not what engage does: EngageUpdateService flips New/Occasional users to engagement='Inactive' after 14 days (RECENT_ACCESS_DAYS=14) and EngageEmailService then mails every Inactive user ~weekly (RESEND_INTERVAL_DAYS=7) with no lastaccess upper bound — right through the whole 30/75/120-day reengage window. A lapsed user would get both campaigns. The rollout checklist only excludes in-sequence users from the digest, never from engage. Go-live prerequisite: exclude in-reengage-sequence users from engage (and the digest).

2. List-Unsubscribe HTTP header can't actually unsubscribe. MjmlMailable::addListUnsubscribeHeaders() builds "{site}/unsubscribe/{userId}" — no auth key. The mail-client one-click POST (RFC 8058) arrives with no session, and /unsubscribe/[id] only acts when the browser session already matches id, so it no-ops. The in-body link correctly uses the keyed /one-click-unsubscribe/{id}/{key}. Fix: override addListUnsubscribeHeaders() in ReengageMail to use the keyed URL (the ChatNotification pattern). Gmail/Yahoo require a working one-click header for bulk mail.

🟠 High

3. relevantallowed opt-out is ignored. Candidate selection checks deleted/bouncing/onholidaytill/simplemail but never users.relevantallowed, which EngageEmailService explicitly honours. A user opted out of win-back/marketing mail still gets all three nudges.
4. Daily candidate query full-scans users. whereBetween('lastaccess', …) has no usable index (only the composite (added, lastaccess)), the JSON_EXTRACT predicate is unindexable, and there's no ->select('id') before lazyById, so it pulls every column of every row daily at 15:30 (just before the already-slow engage). Add a lastaccess index and select('id').
5. Plain-text templates HTML-escape user content. text/reengage/nearby.blade.php and impact.blade.php use {{ }} in a text/plain part, so "Kids' bikes & scooters" becomes Kids' bikes & scooters. The codebase documents this exact trap in text/digest/unified.blade.php and uses {!! !!} — the reengage text templates got it backwards. (And the nearby/impact text parts are never rendered by any test.)

🟡 Medium

• Per-group engagement opt-out uses MAX(...) over all Freegle memberships (not just Approved), so '1' from any stale row overrides a deliberate '0'.
• Stage-1 promises "N items … up for grabs" from offerCount (no photo requirement) but the cards require whereHas('attachments') → promise with an empty grid when nearby offers lack photos.
• Subject line: "1 free things near you this week" (no singular; body pluralises correctly).
• Stage-2 mixes lookback windows: neighbour faces use 30 days, item photos use 7 days.
• HTML/text parity: avatars capped at 4, names at 3 (HTML) vs 5 (text).
• Send-then-record isn't atomic and there's no unique (userid, stage) — a failed insert after a successful spool resends the stage; a manual run overlapping the cron can double-send.

🖼️ UI review (mailpit, headless Chrome, GPU off)

Stage 1 renders clean and on-brand: green hero + logo, warm "Hi Alex", localised "47 free items … near you", a 2-col item-card grid, one clear primary CTA, secondary "Give it away", correct footer with unsubscribe + charity reg. In preview the item images are the "?" placeholder tiles (sample data has no photos) — this is exactly the finding above: with real-but-photoless offers the grid would collapse, so the empty/photoless state needs a graceful fallback (hide the grid, keep the CTA). Stages 2/3 are visually consistent.

📊 Effectiveness instrumentation — currently a gap (being added)

The mail is invisible to open/click tracking (no TrackableEmail, no pixel, no wrapped links → zero rows in email_tracking), and outcome='Reengaged' is declared but never written (re-engagement is only inferred from mutable lastaccess). So today nothing can graph effectiveness. Being added on this branch: wire TrackableEmail (opens/clicks via the existing email_tracking infra), record a per-send email_tracking_id, a daily outcome job that writes real reengaged_at/via from the logs/messages event trail, and a Reengagement sysadmin tab (sent → opened → clicked → reengaged funnel per stage/arm/segment).

🧪 Experiment / variants / journey (being added)

Also on this branch: config-driven experiment arms with a real control holdout (recorded but unmailed, so lift is measurable), stable per-user assignment (crc32(userId|experiment) % 100, same arm across all 3 stages), a rollout_pct knob layered on the existing allowlist for a limited pilot, alternate copy variants, and journey segmentation by first action when joining (offer / wanted / replier / other) so copy can differ by how the user first used Freegle.