Introduction
Laravel provides a clean, simple API over the popular SwiftMailer
library. Laravel provides drivers for SMTP, Mailgun,
Mandrill, SparkPost, Amazon SES, PHP's mail
function, and sendmail, allowing you to
quickly get started sending mail through a local or
cloud based service of your choice.
Driver Prerequisites
The API based drivers such as Mailgun and Mandrill are
often simpler and faster than SMTP servers. All of the
API drivers require that the Guzzle HTTP library be
installed for your application. You may install Guzzle
to your project by adding the following line to your
composer.json file:
"guzzlehttp/guzzle": "~5.3|~6.0"
Mailgun Driver
To use the Mailgun driver, first install Guzzle, then set
the driver option in your
config/mail.php configuration file to
mailgun. Next, verify that your
config/services.php configuration file
contains the following options:
'mailgun' => [
'domain' => 'your-mailgun-domain',
'secret' => 'your-mailgun-key',
],
Mandrill Driver
To use the Mandrill driver, first install Guzzle, then
set the driver option in your
config/mail.php configuration file to
mandrill. Next, verify that your
config/services.php configuration file
contains the following options:
'mandrill' => [
'secret' => 'your-mandrill-key',
],
SparkPost Driver
To use the SparkPost driver, first install Guzzle, then
set the driver option in your
config/mail.php configuration file to
sparkpost. Next, verify that your
config/services.php configuration file
contains the following options:
'sparkpost' => [
'secret' => 'your-sparkpost-key',
],
SES Driver
To use the Amazon SES driver, install the Amazon AWS SDK
for PHP. You may install this library by adding the
following line to your composer.json file's
require section:
"aws/aws-sdk-php": "~3.0"
Next, set the driver option in your
config/mail.php configuration file to
ses. Then, verify that your
config/services.php configuration file
contains the following options:
'ses' => [
'key' => 'your-ses-key',
'secret' => 'your-ses-secret',
'region' => 'ses-region', // e.g. us-east-1
],
Sending Mail
Laravel allows you to store your e-mail messages in views. For example, to
organize your e-mails, you could create an
emails directory within your
resources/views directory:
To send a message, use the send method on
the Mail facade.
The send method accepts three arguments.
First, the name of a view that
contains the e-mail message. Secondly, an array of data
you wish to pass to the view. Lastly, a
Closure callback which receives a message
instance, allowing you to customize the recipients,
subject, and other aspects of the mail message:
<?php
namespace App\Http\Controllers;
use Mail;
use App\User;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
/**
* Send an e-mail reminder to the user.
*
* @param Request $request
* @param int $id
* @return Response
*/
public function sendEmailReminder(Request $request, $id)
{
$user = User::findOrFail($id);
Mail::send('emails.reminder', ['user' => $user], function ($m) use ($user) {
$m->from('hello@app.com', 'Your Application');
$m->to($user->email, $user->name)->subject('Your Reminder!');
});
}
}
Since we are passing an array containing the
user key in the example above, we could
display the user's name within our e-mail view using the
following PHP code:
<?php echo $user->name; ?>
Note: A
$messagevariable is always passed to e-mail views, and allows the inline embedding of attachments. So, you should avoid passing amessagevariable in your view payload.
Building The Message
As previously discussed, the third argument given to the
send method is a Closure
allowing you to specify various options on the e-mail
message itself. Using this Closure you may specify other
attributes of the message, such as carbon copies, blind
carbon copies, etc:
Mail::send('emails.welcome', $data, function ($message) {
$message->from('us@example.com', 'Laravel');
$message->to('foo@example.com')->cc('bar@example.com');
});
Here is a list of the available methods on the
$message message builder instance:
$message->from($address, $name = null);
$message->sender($address, $name = null);
$message->to($address, $name = null);
$message->cc($address, $name = null);
$message->bcc($address, $name = null);
$message->replyTo($address, $name = null);
$message->subject($subject);
$message->priority($level);
$message->attach($pathToFile, array $options = []);
// Attach a file from a raw $data string...
$message->attachData($data, $name, array $options = []);
// Get the underlying SwiftMailer message instance...
$message->getSwiftMessage();
Note: The message instance passed to a
Mail::sendClosure extends the SwiftMailer message class, allowing you to call any method on that class to build your e-mail messages.
Mailing Plain Text
By default, the view given to the send
method is assumed to contain HTML. However, by passing
an array as the first argument to the send
method, you may specify a plain text view to send in
addition to the HTML view:
Mail::send(['html.view', 'text.view'], $data, $callback);
Or, if you only need to send a plain text e-mail, you may
specify this using the text key in the
array:
Mail::send(['text' => 'view'], $data, $callback);
Mailing Raw Strings
You may use the raw method if you wish to
e-mail a raw string directly:
Mail::raw('Text to e-mail', function ($message) {
//
});
Attachments
To add attachments to an e-mail, use the
attach method on the $message
object passed to your Closure. The attach
method accepts the full path to the file as its first
argument:
Mail::send('emails.welcome', $data, function ($message) {
//
$message->attach($pathToFile);
});
When attaching files to a message, you may also specify
the display name and / or MIME type by passing an
array as the second argument to the
attach method:
$message->attach($pathToFile, ['as' => $display, 'mime' => $mime]);
The attachData method may be used to attach
a raw string of bytes as an attachment. For example, you
might use this method if you have generated a PDF in
memory and want to attach it to the e-mail without
writing it to disk:
$message->attachData($pdf, 'invoice.pdf');
$message->attachData($pdf, 'invoice.pdf', ['mime' => $mime]);
Inline Attachments
Embedding An Image In An E-Mail View
Embedding inline images into your e-mails is typically
cumbersome; however, Laravel provides a convenient way
to attach images to your e-mails and retrieving the
appropriate CID. To embed an inline image, use the
embed method on the $message
variable within your e-mail view. Remember, Laravel
automatically makes the $message variable
available to all of your e-mail views:
<body>
Here is an image:
<img src="<?php echo $message->embed($pathToFile); ?>">
</body>
Embedding Raw Data In An E-Mail View
If you already have a raw data string you wish to embed
into an e-mail message, you may use the
embedData method on the
$message variable:
<body>
Here is an image from raw data:
<img src="<?php echo $message->embedData($data, $name); ?>">
</body>
Queueing Mail
Queueing A Mail Message
Since sending e-mail messages can drastically lengthen
the response time of your application, many developers
choose to queue e-mail messages for background sending.
Laravel makes this easy using its built-in unified queue API. To queue a
mail message, use the queue method on the
Mail facade:
Mail::queue('emails.welcome', $data, function ($message) {
//
});
This method will automatically take care of pushing a job onto the queue to send the mail message in the background. Of course, you will need to configure your queues before using this feature.
Delayed Message Queueing
If you wish to delay the delivery of a queued e-mail
message, you may use the later method. To
get started, simply pass the number of seconds by which
you wish to delay the sending of the message as the
first argument to the method:
Mail::later(5, 'emails.welcome', $data, function ($message) {
//
});
Pushing To Specific Queues
If you wish to specify a specific queue on which to push
the message, you may do so using the
queueOn and laterOn
methods:
Mail::queueOn('queue-name', 'emails.welcome', $data, function ($message) {
//
});
Mail::laterOn('queue-name', 5, 'emails.welcome', $data, function ($message) {
//
});
Mail & Local Development
When developing an application that sends e-mail, you probably don't want to actually send e-mails to live e-mail addresses. Laravel provides several ways to "disable" the actual sending of e-mail messages.
Log Driver
One solution is to use the log mail driver
during local development. This driver will write all
e-mail messages to your log files for inspection. For
more information on configuring your application per
environment, check out the configuration
documentation.
Universal To
Another solution provided by Laravel is to set a
universal recipient of all e-mails sent by the
framework. This way, all the emails generated by your
application will be sent to a specific address, instead
of the address actually specified when sending the
message. This can be done via the to option
in your config/mail.php configuration
file:
'to' => [
'address' => 'dev@domain.com',
'name' => 'Dev Example'
],
Mailtrap
Finally, you may use a service like Mailtrap and the
smtp driver to send your e-mail messages to
a "dummy" mailbox where you may view them in a
true e-mail client. This approach has the benefit of
allowing you to actually inspect the final e-mails in
Mailtrap's message viewer.
Events
Laravel fires an event just before sending mail messages.
Remember, this event is fired when the mail is
sent, not when it is queued. You may register
an event listener in your
EventServiceProvider:
/**
* The event listener mappings for the application.
*
* @var array
*/
protected $listen = [
'Illuminate\Mail\Events\MessageSending' => [
'App\Listeners\LogSentMessage',
],
];