Laravel Hack: White labelling markdown emails
Tags: laravel, php
Published: 2020-04-29 17:01:39

---
title: Laravel Hack: White labelling markdown emails
published: true
date: 2020-04-26 17:51:04 UTC
tags: laravel,php
canonical_url: 
---

![](https://cdn-images-1.medium.com/max/1024/0*PkKoslVAvBz1ymz1)<figcaption>Photo by <a href="https://unsplash.com/@westwardwayphotography?utm_source=medium&amp;utm_medium=referral">ASHLEY EDWARDS</a> on <a href="https://unsplash.com?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption>

White labelling is the business practise of making aspects of your application styled to how your clients want it to look. In most cases of a web application serving many clients will want some form of customising of logos and company colours on pages.

In one instance recently though I had to build a way of adding this customisation, not to the frontend of the application but to the email templates. Not only did I need to add different logos which was a fairly simple task but I also needed to add different colours to certain sections of text as well as change the colour of buttons. There was a couple was ways of doing this but these would likely be quite difficult to work with long term. To begin with coming to my solution I just want to quickly explain how _markdown_ emails work in Laravel and what sets the styles delivered in the final _HTML_.

### Markdown emails explained

How markdown emails work is essentially the _HTML_ is generated from a mix of _Blade_ templates with HTML and _Markdown_ that gets converted to HTML. Once that is done the Laravel framework uses what it refers to as a theme, the default is a CSS file. It then begins a process that is called _CSS Inlining_. This is done because HTML Emails cannot use CSS refer links. Instead the styles defined in the theme CSS are converted to style attributes and assigned to the classes applied in the HTML nodes.

To cut a long story short, this:

{% gist https://gist.github.com/peterfox/c5fee8e5ee8f9a6f1efde60e670e4f3b %}

{% gist https://gist.github.com/peterfox/e86375426c7029e8d2dfda674d8f1156 %}

Would then become this:

{% gist https://gist.github.com/peterfox/4951f7e3d8d754a2a3bb598da198b438 %}

The problem is it’s not clear what you can and can’t do with the theme. It looks like it’s just a static CSS file that has to be selected for the notification, the [documentation for this is actually pretty brief](https://laravel.com/docs/7.x/mail#customizing-the-components). This is a bit of problem if you have your styles set in a database etc.

There is a fairly simple solution though. In actual fact, if you dive into the code for Laravel you’ll find that you can use a Blade file instead of a CSS one and the _Blade_ file will still receive all the parameters your _Markdown_ template would. We can actually leverage this into applying minor tweaks to our CSS that will be used for _HTML_ inlining.

### Making a dynamic theme

So I’ve explained the how notifications are styled, I’ll quickly show you how you can take advantage of this to make dynamic emails based on who you’re delivering to.

The first step is to create the blade theme file. I’m just going to copy the original one (For _Laravel 7_ at least) which you can find in this [gist I made](https://gist.github.com/peterfox/f879d10f2801491557d942430572c567). Then we’re going to add our theme to resources/views/vendors/mail/html/themes/whitelabel.blade.php which will contain all the CSS. The folders don’t exist by default so you’ll need to add them.

Then we need to change a simple section in our _whitelabel.blade.php_ file so that in the event of a custom button attribute, the colour for the button is applied and if the custom style isn’t there you can just use the default.

{% gist https://gist.github.com/peterfox/9f5a206b35c7aa89e972f87eeb3bd4d5 %}

What I’ve done now is set up a process that changes the default primary button in the CSS to use a bespoke colour when the custom styles parameter is present.

What we need now it to customise the mail message to enact this change in a relatively clean manner. I’ll first create an extending class of the _MailMessage_ class used in notifications to instead provide a method which can set this button colour.

{% gist https://gist.github.com/peterfox/42c54da552afef06c424490e3a9a3d37 %}

So then if we make a Notification we can replace the _MailMessage_ returned in the toMail method with a _CustomMailMessage_ that can accept our argument.

{% gist https://gist.github.com/peterfox/dfbf419dffc4dd4047b92c32d59538d4 %}

This way we can override the colour of the button in our markdown emails. Such as I set up a simple little route in my app to display these changes via a parameter in a url. Obviously you will likely want to build on this and actually determine the colours or provide other CSS styles based on the User you’re sending the notification to. Just so you can get an idea of how this turns out as an end result I’ve provided some screenshots below.

The original notification email:

![](https://cdn-images-1.medium.com/max/612/1*bWrT7NUBRv5Rmqmb-QBOTA.png)

The email with a color applied via the dynamic theme:

![](https://cdn-images-1.medium.com/max/612/1*aJ7Xfzrzsc6EX-UEpP-LRQ.png)

### Conclusion

This is not a fool proof way of doing it. You will likely run into problems if you need to make drastic changes per client that wants emails styles a particular way but if you want to produce something simple very quickly and don’t mind mixing your blade and CSS this is a pretty effective technique compared to building components that apply special classes to HTML elements which can become equally as unmanageable. My suggest is that if you do need more you should consider looking at extending the \Illuminate\Mail\Markdown class to handle your dynamic needs.

If you’d like to view the code for this demo you can access it on [GitHub](https://github.com/peterfox/whitelabel-emails-demo).

I’m Peter Fox, a software developer in the UK who works with Laravel among other things. If you want to know more about me you can at [https://www.peterfox.me](https://www.peterfox.me/) and feel free to follow me @[SlyFireFox](https://twitter.com/SlyFireFox) on twitter for more Laravel tips and tutorials in the future.