Introduction
Laravel provides a clean, simple API over the popular SwiftMailer library with drivers for SMTP, Mailgun, Postmark, SparkPost, Amazon SES, 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, SparkPost, and Postmark are often simpler and faster than SMTP servers. If possible, you should use one of these drivers. All of the API drivers require the Guzzle HTTP library, which may be installed via the Composer package manager:
composer require guzzlehttp/guzzle
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',
],
If you are not using the "US" Mailgun region, you may define your region's endpoint in the services
configuration file:
'mailgun' => [
'domain' => 'your-mailgun-domain',
'secret' => 'your-mailgun-key',
'endpoint' => 'api.eu.mailgun.net',
],
Postmark Driver
To use the Postmark driver, install Postmark's SwiftMailer transport via Composer:
composer require wildbit/swiftmailer-postmark
Next, install Guzzle and set the driver
option in your config/mail.php
configuration file to postmark
. Finally, verify that your config/services.php
configuration file contains the following options:
'postmark' => [
'token' => 'your-postmark-token',
],
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',
],
If necessary, you may also configure which API endpoint should be used:
'sparkpost' => [
'secret' => 'your-sparkpost-key',
'options' => [
'endpoint' => 'https://api.eu.sparkpost.com/api/v1/transmissions',
],
],
SES Driver
To use the Amazon SES driver you must first 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 and running the composer update
command:
"aws/aws-sdk-php": "~3.0"
Next, set the driver
option in your config/mail.php
configuration file to ses
and 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
],
If you need to include additional options when executing the SES SendRawEmail
request, you may define an options
array within your ses
configuration:
'ses' => [
'key' => 'your-ses-key',
'secret' => 'your-ses-secret',
'region' => 'ses-region', // e.g. us-east-1
'options' => [
'ConfigurationSetName' => 'MyConfigurationSet',
'Tags' => [
[
'Name' => 'foo',
'Value' => 'bar',
],
],
],
],
Generating Mailables
In Laravel, each type of email sent by your application is represented as a "mailable" class. These classes are stored in the app/Mail
directory. Don't worry if you don't see this directory in your application, since it will be generated for you when you create your first mailable class using the make:mail
command:
php artisan make:mail OrderShipped
Writing Mailables
All of a mailable class' configuration is done in the build
method. Within this method, you may call various methods such as from
, subject
, view
, and attach
to configure the email's presentation and delivery.
Configuring The Sender
Using The from
Method
First, let's explore configuring the sender of the email. Or, in other words, who the email is going to be "from". There are two ways to configure the sender. First, you may use the from
method within your mailable class' build
method:
/**
* Build the message.
*
* @return $this
*/
public function build()
{
return $this->from('example@example.com')
->view('emails.orders.shipped');
}
Using A Global from
Address
However, if your application uses the same "from" address for all of its emails, it can become cumbersome to call the from
method in each mailable class you generate. Instead, you may specify a global "from" address in your config/mail.php
configuration file. This address will be used if no other "from" address is specified within the mailable class:
'from' => ['address' => 'example@example.com', 'name' => 'App Name'],
In addition, you may define a global "reply_to" address within your config/mail.php
configuration file:
'reply_to' => ['address' => 'example@example.com', 'name' => 'App Name'],
Configuring The View
Within a mailable class' build
method, you may use the view
method to specify which template should be used when rendering the email's contents. Since each email typically uses a Blade template to render its contents, you have the full power and convenience of the Blade templating engine when building your email's HTML:
/**
* Build the message.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped');
}
You may wish to create a resources/views/emails
directory to house all of your email templates; however, you are free to place them wherever you wish within your resources/views
directory.
Plain Text Emails
If you would like to define a plain-text version of your email, you may use the text
method. Like the view
method, the text
method accepts a template name which will be used to render the contents of the email. You are free to define both an HTML and plain-text version of your message:
/**
* Build the message.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped')
->text('emails.orders.shipped_plain');
}