Statamic Email Templates Laravel Package

Getting Started

This is a Statamic addon with two distinct surfaces: the Control Panel settings screen, and email rendering via EmailTemplates::resolve(). v2.9.0 changed the first (CP nav placement); v2.9.1 changed the second (an opt-out from the branded email shell). Neither touches front-end page rendering or headless/API-only setups.

Minimal steps:

1. Require the addon via Composer and let Statamic's addon discovery pick it up (no manual service provider registration if auto-discovery is intact).
2. Check versions: you need addon v2.9.1 for the branded => false opt-out, and statamic-brand-context 1.16+ for the nested settings nav introduced in v2.9.0. Use composer show or composer.lock.
3. Confirm where your email templates are rendered — the CP settings screen is under Settings (or nested beneath the addon's own nav entry at brand-context 1.16+), but the new behaviour is in the fallback chain your own code supplies.

First use case to verify after upgrading: take a template that falls through to one of your fallbacks and is a complete HTML document (marketing/newsletter files carrying their own header and footer), with a branded layout configured. Send it to yourself and open it on a phone. Then add branded => false to the array that fallback returns and confirm: one header and footer (not two), and no horizontal scrolling on mobile.

Implementation Patterns

The v2.9.1 change is a small contract addition to the fallback return array — a consume change for most teams, an author change if you own fallbacks.

• Opt out per template, not globally. branded => false is returned by the caller's fallback, so granularity lives in your resolution code. Complete documents (marketing templates, imported designs, anything with <html>/doctype and its own header+footer) opt out; transactional mail (order confirmations, password resets, receipts) should stay inside the branded shell for visual consistency and because that shell likely carries your footer, unsubscribe link, and postal address.
• Decide from intent, not from a string sniff. If your fallback factory knows "this is a full document", pass the flag explicitly. A str_contains($html, '<html') heuristic is a reasonable safety net for imported templates, but don't make it the primary rule — a fragment containing a stray <html-ish string shouldn't silently lose your footer.
• Centralise fallback construction. If several mailables build fallback arrays, put them behind one small helper (or a FullTemplate/BrandedTemplate value object) so branded is decided in one place. Scattered arrays are how you end up with one template double-framed and nobody noticing until a campaign ships.
• Pair the upgrade, don't stagger it. Upgrading the addon alone is safe but leaves older grouping in the CP; upgrading brand-context alone leaves the old email behaviour. Rolling both in one deploy gives you the intended layout in both surfaces.
• Keep nav concerns separate from email concerns in docs. If your onboarding material describes CP navigation, note the brand-context 1.16 threshold; for email, note the addon 2.9.1 threshold. They are independent version floors.
• Prefer route links over menu paths in internal runbooks. With brand-context 1.16+, addons without their own CP nav share a single "Addon-Suite" page under Settings, so a described menu path ages badly.

Gotchas and Tips

• The double-frame bug is invisible without a branded layout configured. If you can't reproduce a duplicated header/footer or a mobile-overflowing email, check whether a branded layout is actually set in that environment first. Testing only in a bare local setup will tell you nothing.
• Mobile overflow is a symptom, not a CSS bug. Emails wider than the viewport with a branded layout often mean the shell's width/padding table is nesting inside the template's own container. Before rewriting media queries, count how many times your brand header markup appears in the output — two means double-wrapping.
• Don't opt out of the shell carelessly. branded => false returns the body as-is: no wrapper header, and crucially no wrapper footer. If your unsubscribe link, preference centre link, or physical mailing address lived in the branded layout, an opted-out template now legally needs to carry its own. Marketing's files do; a hand-rolled fallback probably doesn't.
• It's a per-call key, not config. Don't look for a publishable config toggle, environment variable, or config/statamic/* entry — there isn't one, and nothing needs migrating for either release. If a deploy checklist says to publish or migrate, the checklist is stale.
• Unknown-key behaviour on older versions is untested in this release. If you run a fleet with mixed addon versions (or a queued worker on a stale release), upgrade the package before shipping fallbacks that return branded. Verify on staging rather than assuming an older version ignores the key gracefully.
• Silent no-op on old brand-context. settingsNavParent() is ignored below brand-context 1.16. If a stakeholder expects the nested CP layout and doesn't see it, check that version before debugging the addon.
• Nav caching. After upgrading, an unchanged CP menu usually means cached nav: php artisan statamic:stache:clear and php artisan cache:clear before assuming failure. For email changes not appearing, clear compiled views (php artisan view:clear) and confirm which fallback actually resolved.
• Quiet failure on nav placement. A mismatched [section, name] tuple in settingsNavParent() typically falls back to the shared Addon-Suite page rather than erroring — inspect the tuple against registered nav entries when a link lands somewhere unexpected.
• Extension point for your own addons. If you ship internal addons, implementing settingsNavParent() is now the idiomatic way to attach settings to your own nav entry instead of relying on the shared page — same brand-context version floor applies.
• Low-risk releases overall. No breaking changes, no deprecations, no data changes in either version. The real work is a permission/visual check of the CP screen and one rendered-email check with a branded layout enabled.