“Classic” Mail

There are two different syntaxes in Laravel for sending mail: classic and mailable. The mailable syntax is the preferred syntax since 5.3, so we’re going to focus on that in this book. But for those who are working in 5.2 or earlier, here’s a quick look at how the classic syntax (Example 15-1) works.

Mail::send(
    'emails.assignment-created',
    ['trainer' => $trainer, 'trainee' => $trainee],
    function ($m) use ($trainer, $trainee) {
        $m->from($trainer->email, $trainer->name);
        $m->to($trainee->email, $trainee->name)->subject('A New Assignment!');
    }
);

The first parameter of Mail::send() is the name of the view. Keep in mind that emails.assignment-created means resources/views/emails/assignment-created​.blade.php or resources/views/emails/assignment-created.php.

The second parameter is an array of data that you want to pass to the view.

The third parameter is a closure, in which you define how and where to send the email: from, to, CC, BCC, subject, and any other metadata. Make sure to use any variables you want access to within the closure. And note that the closure is passed one parameter, which we’ve named $m; this is the message object.

Take a look at the old docs to learn more about the classic mail syntax.

Basic “Mailable” Mail Usage

Laravel 5.3 introduced a new mail syntax called the “mailable.” It works the same as the classic mail syntax, but instead of defining your mail messages in a closure, you instead create a specific PHP class to represent each mail.

To make a mailable, use the make:mail Artisan command:

php artisan make:mail AssignmentCreated

Example 15-2 shows what that class looks like.

<?php

namespace AppMail;

use IlluminateBusQueueable;
use IlluminateMailMailable;
use IlluminateQueueSerializesModels;
use IlluminateContractsQueueShouldQueue;

class AssignmentCreated extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * Create a new message instance
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Build the message
     *
     * @return $this
     */
    public function build()
    {
        return $this->view('view.name');
    }
}

This class probably looks familiar—it’s shaped almost the same as a Job. It even imports the Queuable trait for queuing your mail and the SerializesModels trait so any Eloquent models you pass to the constructor will be serialized correctly.

So, how does this work? The build() method on a mailable is where you’re going to define which view to use, what the subject is, and anything else you want to tweak about the mail except who it’s going to. The constructor is the place where you’ll pass in any data, and any public properties on your mailable class will be available to the template.

Take a look at Example 15-3 to see how we might update the autogenerated mailable for our assignment example.

<?php

namespace AppMail;

use IlluminateBusQueueable;
use IlluminateMailMailable;
use IlluminateQueueSerializesModels;
use IlluminateContractsQueueShouldQueue;

class AssignmentCreated extends Mailable
{
    use Queueable, SerializesModels;

    public $trainer;
    public $trainee;

    public function __construct($trainer, $trainee)
    {
        $this->trainer = $trainer;
        $this->trainee = $trainee;
    }

    public function build()
    {
        return $this->subject('New assignment from ' . $this->trainer->name)
            ->view('emails.assignment-created');
    }
}

Example 15-4 shows how to send a mailable.

// Simple send
Mail::to($user)->send(new AssignmentCreated($trainer, $trainee));

// With CC/BCC/etc.
Mail::to($user1))
    ->cc($user2)
    ->bcc($user3)
    ->send(new AssignmentCreated($trainer, $trainee));

// With collections
Mail::to('[email protected]')
    ->bcc(User::all())
    ->send(new AssignmentCreated($trainer, $trainee))

Mail Templates

Mail templates are just like any other template. They can extend other templates, use sections, parse variables, contain conditional or looping directives, and do anything else you can do in a normal Blade view.

Take a look at Example 15-5 to see a possible emails.assignment-created template for Example 15-3.

<!-- resources/views/emails/assignment-created.blade.php -->
<p>Hey {{ $trainee->name }}!</p>

<p>You have received a new training assignment from <b>{{ $trainer->name }}</b>.
Check out your <a href="{{ route('training-dashboard') }}">training
dashboard</a> now!</p>

In Example 15-3, both $trainer and $trainee are public properties on your mailable, which makes them available to the template.

If you want to explicitly define which variables are passed to the template, you can chain the with() method onto your build() call as in Example 15-6.

public function build()
{
    return $this->subject('You have a new assignment!')
        ->view('emails.assignment')
        ->with(['assignment' => $this->event->name]);
}

public function build()
{
    return $this->view('emails.reminder')
        ->text('emails.reminder_plain');
}

Methods Available in build()

Here are a few of the methods available to you to customize your message in the build() method of your mailable:

from($address, $name = null)

Sets the “from” name and address—represents the author

subject($subject)

Sets the email subject

attach($file, array $options = [])

Attaches a file; valid options are mime for MIME type and as for display name

attachData($data, $name, array $options = [])

Attaches a file from a raw string; same options as attach()

attachFromStorage($path, $name = null, array $options = [])

Attaches a file stored on any of your filesystem disks

priority($level = n)

Set the email’s priority, where 1 is the highest and 5 is the lowest

Finally, if you want to perform any manual modifications on the underlying Swift message, you can do that using withSwiftMessage(), as shown in Example 15-7.

public function build()
{
    return $this->subject('Howdy!')
        ->withSwiftMessage(function ($swift) {
            $swift->setReplyTo('[email protected]');
        })
        ->view('emails.howdy');
}

Attachments and Inline Images

Example 15-8 shows three options for how to attach files or raw data to your email.

// Attach a file using the local filename
public function build()
{
    return $this->subject('Your whitepaper download')
        ->attach(storage_path('pdfs/whitepaper.pdf'), [
            'mime' => 'application/pdf', // Optional
            'as' => 'whitepaper-barasa.pdf', // Optional
        ])
        ->view('emails.whitepaper');
}

// Attach a file passing the raw data
public function build()
{
    return $this->subject('Your whitepaper download')
        ->attachData(
            file_get_contents(storage_path('pdfs/whitepaper.pdf')),
            'whitepaper-barasa.pdf',
            [
                'mime' => 'application/pdf', // Optional
            ]
        )
        ->view('emails.whitepaper');
}

// Attach a file stored on one of your filesystem disks, like S3
public function build()
{
    return $this->subject('Your whitepaper download')
        ->view('emails.whitepaper')
        ->attachFromStorage('/pdfs/whitepaper.pdf');
}

And you can see how to embed images directly into your email in Example 15-9.

<!-- emails/image.blade.php -->
Here is an image:

<img src="{{ $message->embed(storage_path('embed.jpg')) }}">

Or, the same image embedding the data:

<img src="{{ $message->embedData(
    file_get_contents(storage_path('embed.jpg')), 'embed.jpg'
) }}">

Markdown Mailables

Markdown mailables allow you to write your email content in Markdown, after which it will be converted into full HTML (and plain-text) emails with Laravel’s built-in, responsive HTML templates. You can also tweak these templates to make a customized email template that it’s simple for your developers and nondevelopers to create content for.

First, run the make:mail Artisan command with the markdown flag:

php artisan make:mail AssignmentCreated --markdown=emails.assignment-created

You can see an example of what the mail file it’ll generate looks like in Example 15-10.

class AssignmentCreated extends Mailable
{
    // ...

    public function build()
    {
        return $this->markdown('emails.assignment-created');
    }
}

As you can see, this is almost exactly the same as a normal mailable file in Laravel. The main difference is that you’re calling the markdown() method instead of the view() method. Also note that the template you’re referencing should represent a Markdown template, not a normal Blade template.

The difference is that, whereas a normal email template may be expected—with the use of includes and inheritance like any Blade file—to generate a full HTML email, Markdown templates simply pass Markdown content to a few predefined components. Framework and package-level components in Laravel are often nested with a package::component naming style, and as such the main body of your Markdown email should be passed into a component named mail::message. Take a look at Example 15-11 to see an example of a simple Markdown mail template.

{{-- resources/views/emails/assignment-created.blade.php --}}
@component('mail::message')
# Hey {{ $trainee->name }}!

You have received a new training assignment from **{{ $trainer->name }}**

@component('mail::button', ['url' => route('training-dashboard')])
View Your Assigment
@endcomponent

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

As you can see in Example 15-11, there’s a parent mail::message component to which you pass the body of your email, but you’re also provided with other smaller components you can sprinkle into your emails. We used the mail::button component here, which takes a body (“View Your Assignment”) but also requires parameters to be passed, as an array to the second parameter of the @component directive.

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

Rendering Mailables to the Browser

When you’re developing emails in your applications, it’s helpful to be able to preview how they’ll render. You can rely on a tool like Mailtrap for this, and that is a useful tool, but it can also be helpful to render the mails directly in your browser and see your changes made immediately.

Take a look at Example 15-12 to see a sample route you can add to your application to render a given mailable.

Route::get('preview-assignment-created-mailable', function () {
    $trainer = Trainer::first();
    $trainee = Trainee::first();

    return new AppMailAssignmentCreated($trainer, $trainee);
});

In Laravel 5.8+ we can also quickly preview a notification in the browser.

Route::get('preview-notification', function () {
    $trainer = Trainer::first();
    $trainee = Trainee::first();

    return (new AppNotificationsAssignmentCreated($trainer, $trainee))
        ->toMail($trainee);
});

Queues

Sending email is a time-consuming task that can cause applications to slow down, so it’s common to move it to a background queue. It’s so common, in fact, that Laravel has a set of built-in tools to make it easier to queue your messages without writing queue jobs for each email:

queue()

To queue a mail object instead of sending it immediately, simply pass your mailable object to Mail::queue() instead of Mail::send():

    Mail::queue(new AssignmentCreated($trainer, $trainee));

later()

Mail::later() works the same as Mail::queue(), but it allows you to add a delay—either in minutes, or at a specific time by passing an instance of DateTime or Carbon—specifying when the email will be pulled from the queue and sent:

    $when = now()->addMinutes(30);
    Mail::later($when, new AssignmentCreated($trainer, $trainee));

For both queue() and later(), if you’d like to specify which queue or queue connection your mail is added to, use the onConnection() and onQueue() methods on your mailable object:

$message = (new AssignmentCreated($trainer, $trainee))
    ->onConnection('sqs')
    ->onQueue('emails');

Mail::to($user)->queue($message);

If you’d like to direct that a given mailable should always be queued, you can make the mailable implement the IlluminateContractsQueueShouldQueue interface.

Local Development

This is all well and good for sending mail in your production environments. But how do you test it all out? There are three primary tools you’ll want to consider: Laravel’s log driver, a Software as a Service (SaaS) app named Mailtrap, and the so-called “universal to” configuration option.

Message-ID: <04ee2e97289c68f0c9191f4b04fc0de1@localhost>
Date: Tue, 17 May 2016 02:52:46 +0000
Subject: Welcome to our app!
From: Matt Stauffer <[email protected]>
To: [email protected]
MIME-Version: 1.0
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Welcome to our app!

MAIL_DRIVER=smtp
MAIL_HOST=mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username_from_mailtrap_here
MAIL_PASSWORD=your_password_from_mailtrap_here
MAIL_ENCRYPTION=null

'to' => [
    'address' => '[email protected]',
    'name' => 'Matt Testing My Application'
],

Defining the via() Method for Your Notifiables

As you can see in Example 15-14, we’re somehow responsible for deciding, for each notification and each notifiable, which notification channels we’re going to use.

You could just send everything as mail or just send everything as an SMS (Example 15-15).

public function via($notifiable)
{
    return 'nexmo';
}

You could also let each user choose their one preferred method and save that on the User itself (Example 15-16).

public function via($notifiable)
{
    return $notifiable->preferred_notification_channel;
}

Or, as we imagined in Example 15-14, you could create a method on each notifiable that allows for some complex notification logic. For example, you could notify the user over certain channels during work hours and other channels in the evening. What is important is that via() is a PHP class method, so you can do whatever complex logic you want there.

Sending Notifications

There are two ways to send a notification: by using the Notification facade, or by adding the Notifiable trait to an Eloquent class (likely your User class).

use AppNotificationsWorkoutAvailable;
...
$user->notify(new WorkoutAvailable($workout));

use AppNotificationsWorkoutAvailable;
...
Notification::send($users, new WorkoutAvailable($workout));

Queueing Notifications

Most of the notification drivers need to send HTTP requests to send their notifications, which could slow down your user experience, so you probably want to queue your notifications. All notifications import the Queuable trait by default, so all you need to do is add implements ShouldQueue to your notification and Laravel will instantly move it to a queue.

As with any other queued features, you’ll need to make sure you have your queue settings configured correctly and a queue worker running.

If you’d like to delay the delivery of a notification, you can run the delay() method on the notification:

$delayUntil = now()->addMinutes(15);

$user->notify((new WorkoutAvailable($workout))->delay($delayUntil));

Out-of-the-Box Notification Types

Out of the box, Laravel comes with notification drivers for email, database, broadcast, Nexmo SMS, and Slack. I’ll cover each briefly, but I’d recommend referring to the docs for more thorough introductions to each.

It’s also easy to create your own notification drivers, and dozens of people already have; you can find them at the Laravel Notification Channels website.

Email notifications

Let’s take a look at how the email from our earlier example, Example 15-14, is built:

public function toMail($notifiable)
{
    return (new MailMessage)
        ->line('You have a new workout available!')
        ->action('Check it out now', route('workouts.show', [$this->workout]))
        ->line('Thank you for training with us!');
}

The result is shown in Figure 15-1. The email notification system puts your application’s name in the header of the email; you can customize that app name in the name key of config/app.php.

This email is automatically sent to the email property on the notifiable, but you can customize this behavior by adding a method to your notifiable class named routeNotificationForMail() that returns the email address you’d like email notifications sent to.

The email’s subject is set by parsing the notification class name and converting it to words. So, our WorkoutAvailable notification would have the default subject of “Workout Available”. You can also customize this by chaining the subject() method on the MailMessage in the toMail() method.

If you want to modify the templates, publish them and edit to your heart’s content:

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

Figure 15-1. An email sent with the default notification template

Markdown mail notifications

If you like working with Markdown emails (see “Markdown Mailables”), you can also use the same markdown() method in your notifications, as shown in Example 15-19:

Example 15-19. Using the markdown() method with notifications

public function toMail($notifiable)
{
    return (new MailMessage)
        ->subject('Workout Available')
        ->markdown('emails.workout-available', ['workout' => $this->workout]);
}

You can also change the style of the default template to be an “error” message, which uses a bit of different language and changes the primary button color to red. Just add a call to the error() method to your MailMessage call chain in the toMail() method.

User::first()->notifications->each(function ($notification) {
    // Do something
});

User::first()->unreadNotifications->each(function ($notification) {
    // Do something
});

// Individual
User::first()->unreadNotifications->each(function ($notification) {
    if ($condition) {
        $notification->markAsRead();
    }
});

// All
User::first()->unreadNotifications->markAsRead();

composer require laravel/nexmo-notification-channel

composer require laravel/slack-notification-channel

Mail

There are two options for testing mail in Laravel. If you’re using the traditional mail syntax (which is, by the way, not the preferred method in Laravel 5.3 and later), I’d recommend using a tool called MailThief, which Adam Wathan wrote for Tighten. Once you bring MailThief into your application with Composer, you can use MailThief::hijack() in your tests to make MailThief capture any calls to the Mail facade or any mailer classes.

MailThief then makes it possible to make assertions against the senders, recipients, CC and BCC values, and even content and attachments of your mail. Take a look at the GitHub repo to learn more, or bring it into your app:

composer require tightenco/mailthief --dev

If you’re using mailables, there’s a simple syntax for writing assertions against your sent mail (Example 15-23).

public function test_signup_triggers_welcome_email()
{
    Mail::fake();

    Mail::assertSent(WelcomeEmail::class, function ($mail) {
        return $mail->subject == 'Welcome!';
    });

    // You can also use assertSentTo() to explicitly test the recipients, and
    // you can use assertNotSent() to test that a specific mail wasn't sent.
}

Notifications

Laravel provides a built-in set of assertions for testing your notifications. Example 15-24 demonstrates.

public function test_new_signups_triggers_admin_notification()
{
    Notification::fake();

    Notification::assertSentTo($user, NewUsersSignedup::class,
        function ($notification, $channels) {
            return $notification->user->email == '[email protected]'
            && $channels == ['mail'];
    });

    // Assert that the email was sent to a given user
    Notification::assertSentTo(
        [$user],
        NewUsersSignedup::class
    );

    // You can also use assertNotSentTo()
    Notification::assertNotSentTo(
        [$userDidntSignUp], NewUsersSignedup::class
    );
}