Laravel Mail Editor Laravel Package

Getting Started

The pitch is simple: it is a block-based email template engine that renders to the HTML you would otherwise hand-write in Blade and regret. You get a database-backed template, an editor for non-developers, and a single send call from your app code.

composer require jeffersongoncalves/laravel-mail-editor

Then, in order:

1. Publish and run migrations. You need tables for templates, versions, variants, and brand kits. Publish config before migrating and check the table prefix — this package was extracted from a Filament plugin, so it may ship un-prefixed or mail_editor_-prefixed names that are worth confirming won't collide.
2. Read the config file top to bottom. It is the fastest map of the package: driver/renderer settings, default theme, caching, route registration (if it ships a UI), and the guard/middleware protecting the editor. Everything else follows from here.
3. Find the block registry and the renderer. The 22 blocks are the product. Skim the registry to see how a block declares its fields and its render method — that is the extension point you will actually touch.
4. Create one template and send it. The integration surface is Mail::template($slug, $variables). Start with a single transactional email (order confirmation, password reset) rather than a campaign — you will hit every sharp edge in under an hour and the blast radius is a real user who expects the mail.
5. php artisan list — the release notes mention Artisan commands without naming them. Grep the output for the package's namespace; expect import/export, publish/seed, and probably a render or preview command.

First real use case: replace one Blade email that marketing keeps asking you to tweak. That is the value proposition in one sentence, and it is the right scope for evaluating whether the package earns a place in the stack.

Implementation Patterns

Wrap the facade call in a Mailable. Mail::template() is convenient, but a Mailable class keeps the template slug and its variable contract in one typed place, gives you ->onQueue(), and makes the email testable without the editor UI. Treat the slug plus the variable array as an API consumed by the template author — a change on either side breaks the other.

Make the variable contract explicit. Variables support fallbacks, conditionals and loops, which is great for authors and dangerous for you: a missing key renders an empty string rather than throwing. Build a small DTO or toMailVariables() method per Mailable and assert its shape in a unit test. This is the single highest-value habit with any template engine that tolerates unknowns.

Version control the templates via JSON export. The review workflow and version history live in the database, which means they are not in your repo and not in your PR diffs. Export templates to JSON, commit them, and import on deploy. Do a dry run against staging first and know whether import merges or overwrites before you point it at production.

Respect the draft → review → publish lifecycle, and confirm what renders. Before wiring this into production, check which version Mail::template() resolves — published, latest, or a passed-in version. Then make sure your preview route (auth-gated, internal only) renders the draft while the send path renders the published one. Confusing the two is how half-finished copy reaches customers.

A/B variants need assignment logic you own. The package gives you variants; it does not give you analytics or a deterministic bucketing strategy. Decide the split in your app (hash of user ID, a column on the user, a feature flag), log which variant went out alongside the send, and keep the variant key stable per recipient so a retry does not flip them.

Brand kits and themes for multi-tenant. If this is a SaaS, one template set plus per-tenant brand kits is a far better shape than duplicating templates per tenant. Establish and document the cascade order (block styles → theme → brand kit → base defaults) early; retrofitting it after a hundred templates exist is painful.

Test the output, not the intent. Snapshot the rendered HTML and the plain-text version in a test. Assert that Outlook VML markup is present for buttons, that links carry your UTM parameters, and that a conditional branch flips correctly with and without a variable set.

Queue the send. Rendering tables and inline CSS is not free. The Mailable should always be queued in production.

Gotchas and Tips

• Do not hand-edit the rendered HTML. Table layout, inline CSS, consolidated media queries, and VML are generated as a package. If you need something different, change the block or the theme — patching output gets silently overwritten on the next save.
• Plain-text is generated from the HTML. Custom blocks are the usual place this degrades. Check the text part whenever you add one.
• Conditionals and loops are an evaluation surface. If template authors are trusted staff, fine. If tenants or end users can author templates, treat expressions as untrusted input and be very sure the evaluator is sandboxed. Do not discover this in production.
• The editing lock can strand people. Locks are correct in principle and annoying in practice when someone closes a laptop mid-edit. Find the expiry/release mechanism and document the break-glass command for support.
• The quality, spam, accessibility, and link scores are heuristics. Useful as guardrails, not as a compliance sign-off. They will not tell you that your image-only header is invisible with images off.
• Outlook is still Outlook. VML buttons and table layout get you most of the way; verify in Litmus or Email on Acid before a large send. The dark-mode handling in particular is worth eyeballing on a real client.
• Clear caches after theme or block changes. php artisan config:cache after config edits, and remember compiled views may need clearing after theme updates.
• It is a 1.0.0 extracted from a plugin. Pin the version, check the PHP/Laravel support matrix against your app, and skim the test suite before betting a critical transactional path on it. The extraction is a good sign for design quality — the core is deliberately decoupled from Filament — but the standalone API has no battle history yet.
• Extension points worth knowing before you need them: the block registry (custom blocks), theme overrides (styling without forking), and whatever variable resolution hook exists (computed or global variables, e.g. a {{ year }} or {{ company_name }} injected everywhere). Registering a global variable resolver beats asking every author to remember a fallback.

Overall: a strong fit if non-developers need to own email content and you want the output to be someone else's problem. Keep the variable contract in typed code, keep templates in JSON in git, and it will pay for itself quickly.