Mail Laravel Package

Product Decisions This Supports

• Feature and UX roadmap: The v2.4.0 email-authoring work remains the substantive UX step for a mature block library. With 29 slot types, the grouped tile palette, block search, and separate Blocks/Structure tabs reduce time spent scanning a long list and make advanced blocks discoverable without pushing structure editing out of view. v2.5.3 adds no new user-facing capability; it hardens existing behaviour.
• Security and risk posture (new): v2.5.3 closes a path-traversal issue in MailBuilder::embedCidImages() and CidImageEmbedder::embed(). When a base path is supplied, a relative src such as ../secret could previously attach a file from outside the base directory. Embedded images must now resolve inside the base path, be a regular readable file of at most 5 MB, and have an image MIME type. URLs, stream wrappers (php://, file://) and protocol-relative addresses are never treated as local paths. This is a genuine security fix and should be tracked as such, not as a routine feature update.
• Blast-radius assessment (build vs. buy): The exposure is narrow and precisely described. Only code that passes a base path is affected; calls without one (data-URI only) behave as before. If the product never passes a base path, this is a low-urgency upgrade. If it does — or if any HTML reaching the embedder is user- or customer-authored — treat it as a priority patch. The fact that the vendor shipped a scoped, documented hardening fix with an explicit "update if you pass a base path with HTML you do not fully control" callout is a point in favour of continuing to buy rather than maintain in-house.
• Upgrade and regression planning: Two things to plan for. First, this is a behaviour change, not just a patch: any template or stored content that legitimately referenced an image via a relative path outside the base directory will now silently fail to embed that image. Second, nothing changes in the schema, stored documents, or compiled email output structure, so no data migration is needed. The operational actions are composer update getodden/mail and republishing editor assets.
• Custom palette and integration decisions: Schema export v3 adds groups plus per-slot short_label, group, and description while keeping existing keys unchanged, supporting a future custom palette or editor integration without a schema migration. <odden-mail-editor> remains backward-compatible with schemas lacking the new keys.
• Use cases: Transactional email templates, campaign/template authoring in Laravel admin panels, Filament-based content tools, and products where marketing or ops users assemble emails from structured blocks rather than editing raw HTML. The security fix matters most in multi-tenant or customer-authored-template scenarios.

When to Consider This Package

• Consider adoption when a Laravel application needs a block-based email editor with a broad slot library, especially if non-technical users must add and arrange blocks reliably.
• Consider it when email HTML or template content may originate from users, customers, or tenants and the pipeline embeds local images. v2.5.3 makes the embedder safe by default when a base path is passed, which removes a class of file-disclosure risk that would otherwise require in-house review.
• Consider it when the team wants a schema export that can support a custom palette or external editor surface. The added group and description metadata reduces custom UI effort, and fallback behaviour protects older schemas.
• Consider it when Filament integration is valuable. The release line explicitly supports the Filament field and updates its block forms with the new icons.
• Treat v2.5.3 as a required upgrade if the codebase calls embedCidImages()/embed() with a base path against HTML the team does not fully control. Treat it as a scheduled upgrade if no base path is ever passed.
• Look elsewhere if requirements demand a fully freeform email canvas, complex template logic beyond structured blocks, or a non-Laravel/non-PHP stack where this package's integration model would be friction.
• Be cautious if the deployment process cannot reliably republish vendor assets, or if a self-hosted editor bundle cannot be updated to include icons.js; odden-mail-editor.js now imports it.

How to Pitch It (Stakeholders)

Executive summary: v2.5.3 is a security hardening release for the email builder, not a feature release. It prevents a crafted relative image path in email HTML from attaching a file from outside the permitted asset directory when a base path is configured. The change is narrowly scoped: only deployments that pass a base path are affected, and the fix is a straight upgrade with no data migration. Recommended decision: approve the upgrade as a security patch, and confirm with engineering whether any content pipeline passes a base path with untrusted HTML — that determines whether this is this sprint or next.

Engineering summary: Upgrade with composer update getodden/mail, then republish editor assets using php artisan vendor:publish --tag=mail-builder-assets --force or php artisan filament:assets for the Filament field. Behaviour change: MailBuilder::embedCidImages() and CidImageEmbedder::embed(), when given a base path, now only embed a local image if it resolves inside that base path, is a regular readable file of at most 5 MB, and has an image MIME type. URLs, stream wrappers (php://, file://) and protocol-relative addresses are never treated as local paths. Calls without a base path (data URIs only) are unchanged. Audit for: (a) any stored or seeded templates relying on ../ relative image paths that will now be rejected, and (b) any caller passing a base path alongside user-supplied HTML. Schema export v3 adds top-level groups and per-slot short_label, group, and description; existing keys are unchanged, and the editor still works with schemas missing the new keys. If serving editor files directly, include icons.js alongside the existing assets because odden-mail-editor.js imports it. No new dependency was added; Heroicons are inlined under MIT.