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',
],
];