Laravel Markdown Mailables

// By Dillon Kavanagh

Laravel 5.3 introduced Mailables, the ability to build emails using a mailable class. Mailables control the gathering data and passing that data to views. Laravel 5.4 expands the Mailables functionality by adding the capability to use Markdown Syntax and Blade Components together to provide great flexibility. This article will review how to get started using the new Markdown Mailables.

Markdown is a lightweight markup language with plain text formatting syntax. It’s designed so that it can be converted to HTML and many other formats using a tool by the same name.

Step1: Creating the Markdown Mailables

We are going to create a welcome email for when a user signs up to your application.

The Markdown Mailable boilerplate can be generated by running the following command:

php artisan make:mail Welcome --markdown=emails.welcome

The above command uses the –markdown flag and specifies a view of emails.welcome. After running the command you will see within the app/mail directory you have a welcome.php file and within resources/views/emails directory you have a welcome.blade.php file.

The welcome.php file will include the following build method which makes a reference to a markdown method.


/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    return $this->from('example@example.com')
                ->markdown('emails.welcome');
}

And the resources/views/emails/welcome.blade.php will generate a basic message template using a combination of Blade components and Markdown syntax. Note the use of markdown syntax with the # Introduction.


@component('mail::message')
# Introduction

The body of your message.

@component('mail::button', ['url' => ‘’])
Button Text
@endcomponent

Thanks,
{{ config('app.name') }}
@endcomponent

Step 2: Sending the mail

Within your relevant controller function, when the user signs up to your application we will send the welcome email using the mail facade.

Mail::to($receiverAddress)->send(new Welcome);

Ensure to import your mail class at the top of your controller.

use App\Mail\Welcome;

Now when the function is triggered a welcome mail will be sent to the designated email address.

Currently our welcome email looks like this:
Laravel Mailables Basic Starter Template Preview

Step 3: Customise your mail templates

Basic customisation of the email template can be done by editing the Markdown Syntax and Blade Components.

In the code below we have changed the text for the header and paragraph with Markdown Syntax. A URL has been added to the button component and a new panel component has been inserted below the button.


@component('mail::message')
# Welcome

Thanks for trying our site. We’re thrilled to have you on board.

@component('mail::button', ['url' => 'https://websitename.com'])
Explore our site!
@endcomponent


@component('mail::panel')
If you like our site, follow us on social media!
@endcomponent

Thanks,
{{ config('app.name') }}
@endcomponent

Email Components

The following email components are included by default with the mailables:

  • header
  • footer
  • button
  • layout
  • message
  • panel
  • promotion
  • subcopy
  • table

Our adjusted welcome email now looks like this:
Laravel Mailables Basic Welcome Template Preview

Customise your Mail Components

If you are looking to customise your mail components further, you can publish the mail vendor files to your resources/views directory using the following command:

php artisan vendor:publish --tag=laravel-mail

The mail directory contains html and markdown directories, each directory will contain representations of each component and can be customised however you feel necessary.

Customise the CSS

If you wish to customise the styling of the components, the resources/views/vendor/mail/html/themes directory provides a default.css file. This file can be changed and any style automatically get in-lined to the HTML of your mail messages.

Custom CSS from Scratch

Or if you prefer to start your own theme from scratch you can create a new css file example.css in the resources/views/vendor/mail/html/themes directory and within config/ directory mail.php change the theme to example.


'markdown' => [
    'theme' => 'example',

    'paths' => [
        resource_path('views/vendor/mail'),
    ],
],

Now you can have full control over the look and layout of your mail templates.

Keep Reading

All Projects