Mail Laravel Package

Getting Started

• Upgrade the package with composer update getodden/mail. There is no new dependency to install — the icons ship inlined in resources/js/editor/icons.js (Heroicons v2 outline, MIT).
• Republish the editor assets after upgrading:
  • Standard editor: php artisan vendor:publish --tag=mail-builder-assets --force
  • Filament field: php artisan filament:assets
• Open the mail editor and confirm the redesigned left panel is present: a two-column tile grid, search box, and Blocks/Structure tabs.
• First practical use case: click a tile to insert a block after the currently selected one (or drag it onto the email), then switch to the Structure tab to reorder or select existing blocks.
• Sanity-check the accessibility affordances while you are there: tabs respond to arrow keys, and tiles expose the full block name and description through the tooltip and accessible name.
• If you build your own palette or embed the editor directly, inspect the schema export next. v2.4.0 exports schema version 3 with grouping metadata while remaining compatible with older schemas.
• If you call MailBuilder::embedCidImages() / CidImageEmbedder::embed() with a base path, add a quick smoke test after upgrading: an in-base relative src should still be embedded, while ../secret, file://, php://, protocol-relative //host/x.png, and oversized or non-image files must now be left untouched.

Implementation Patterns

• Use the built-in palette for day-to-day editing. Blocks are grouped under Structure, Content, Columns & layout, Commerce, Engagement, and Data & feeds, making the 29 slot types easier to scan.
• Use block search to find blocks by name, short name, description, or group. It matches every word, so searches like "commerce receipt" or "layout sidebar" work well.
• Switch to the Structure tab rather than scrolling: it is now a single click away instead of sitting below the entire block list. The tabs follow the tabs pattern, so keyboard users get arrow-key navigation — wire this into any custom shell you build around the editor.
• Treat the schema export as the integration contract when building custom palettes or tooling:
  • Top-level groups contains key and label.
  • Each slot now includes short_label, group, and description.
  • Existing schema keys are unchanged.
• Build custom palettes from groups for headings and ordering, slot.group for membership, slot.short_label for compact tile labels, and slot.description for tooltips and search.
• Keep slot type keys as the source of truth. Labels and descriptions are presentation metadata and may change.
• For Filament integrations, use the Filament field and publish assets with php artisan filament:assets after upgrading. The block forms also show the new per-block icons, including the four slots that gained their own glyph: three_column (squares-plus), order_receipt (receipt-percent), dynamic_feed (arrow-path), and labeled_divider (ellipsis-horizontal).
• If you serve editor files yourself, include icons.js alongside the other editor assets. odden-mail-editor.js now imports it.
• Preserve the existing editor fallback behavior in custom implementations: a schema without groups, short_label, group, or description should still render as one list with no headings, full labels, and a fallback icon.
• For CID embedding, pass a base path whenever the HTML is user-supplied and you embed local images — that is the mode the v2.5.3 hardening protects. A typical call looks like embedCidImages($html, basePath: storage_path('app/mail-assets')), with images authored as paths relative to that directory.
• Keep intentionally local images inside the base path, under 5 MB, with a real image MIME type (PNG/JPEG/GIF/WebP/etc.). Anything else is now skipped rather than attached — serve large or exotic assets from a URL instead and let the client fetch them, or pre-process them before embedding.
• If you only ever embed data URIs, nothing changes: call embedCidImages($html) without a base path and behavior is identical to before.

Gotchas and Tips

• Republishing assets is required even though stored documents and compiled email do not change. Stale assets can leave the editor on the old palette or missing the new icon module.
• --force overwrites published files. If you have customized published editor assets, back them up or move customizations into your own asset pipeline before republishing.
• Missing icons.js is a likely failure point when self-hosting editor files. Ensure odden-mail-editor.js can resolve its import; if your bundler or CDN rule set includes editor files by glob, add the new module explicitly.
• Schema version 3 is additive, not a migration. Do not rewrite stored documents or compiled emails for this release.
• Custom palette code should not assume groups exists. Older exports or externally supplied schemas may omit the new keys; fall back to a single ungrouped list.
• Do not rely on icon names or group labels for behavior. Use stable slot type keys and treat grouping metadata as presentation — the four newly distinct icons are a presentation change only.
• If the old palette still appears after upgrading, verify the asset publish command ran against the correct app and check for browser or asset-pipeline caching.
• The tile label is intentionally short; the full block name and description are exposed through the tooltip and accessible name. Keep that distinction when building custom tiles, and make sure your replacement tiles carry the same accessible name rather than just the short label.
• When testing the new tabs, exercise them with the keyboard, not just the mouse — a regression here silently locks keyboard and screen-reader users out of the Structure list entirely.
• v2.5.3 is a security fix: previously a relative src such as ../secret could attach a file from outside the base directory. Update as soon as practical if you pass a base path with HTML you do not fully control (imported templates, CRM/user content, third-party APIs).
• The new rules only apply when a base path is supplied. Calls without one (data-URI-only mode) are unchanged — do not "fix" those call sites.
• Stream wrappers and absolute URLs are never treated as local paths, so a previously working file:///… or php://… src will now silently stay a remote URL in the output. Audit any templates relying on those and convert them to paths relative to the base directory.
• Embedding failures are silent by design (the image is skipped, not thrown), so add your own assertions in tests or log the resulting HTML. Don't assume a green request means every image made it into the MIME parts.
• Watch the 5 MB cap: a resized-on-upload pipeline usually keeps you under it, but full-resolution product shots straight from a camera will now drop out of the email. Check storage for offenders and downscale before embedding.
• MIME detection is content-based, so files with an image extension but a non-image payload (or a truncated/corrupt file) are skipped. Ensure the file is a "regular readable file" — symlinks, directories, and unreadable permissions all fall through.
• Keep the base path as narrow as possible (a dedicated mail-assets directory), not base_path() or storage_path(). The hardening prevents escaping the base path, but a wide base path still permits reading anything you put inside it.