Introduction
Laravel provides a clean, simple API over the popular SwiftMailer library with drivers for SMTP, Mailgun, 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 SparkPost 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',
],
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
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:
public function build()
{
return $this->from('example@example.com')
->view('emails.orders.shipped');
}
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’);
}
Tip!! 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 a HTML and plain-text version of your message:
public function build()
{
return $this->view('emails.orders.shipped')
->text('emails.orders.shipped_plain');
}
Via Public Properties
Typically, you will want to pass some data to your view that you can utilize when rendering the email’s HTML. There are two ways you may make data available to your view. First, any public property defined on your mailable class will automatically be made available to the view. So, for example, you may pass data into your mailable class’ constructor and set that data to public properties defined on the class:
namespace App\Mail;
use App\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
class OrderShipped extends Mailable
{
use Queueable, SerializesModels;
/**
* The order instance.
*
* @var Order
*/
public $order;
/**
* Create a new message instance.
*
* @return void
*/
public function __construct(Order $order)
{
$this->order = $order;
}
/**
* Build the message.
*
* @return $this
*/
public function build()
{
return $this->view('emails.orders.shipped');
}
}
Once the data has been set to a public property, it will automatically be available in your view, so you may access it like you would access any other data in your Blade templates:
Via The with Method:
If you would like to customize the format of your email’s data before it is sent to the template, you may manually pass your data to the view via the with method. Typically, you will still pass data via the mailable class’ constructor; however, you should set this data to protected or private properties so the data is not automatically made available to the template. Then, when calling the with method, pass an array of data that you wish to make available to the template:
namespace App\Mail;
use App\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
class OrderShipped extends Mailable
{
use Queueable, SerializesModels;
/**
* The order instance.
*
* @var Order
*/
protected $order;
/**
* Create a new message instance.
*
* @return void
*/
public function __construct(Order $order)
{
$this->order = $order;
}
/**
* Build the message.
*
* @return $this
*/
public function build()
{
return $this->view(’emails.orders.shipped’)
->with([
‘orderName’ => $this->order->name,
‘orderPrice’ => $this->order->price,
]);
}
}
Attachments
To add attachments to an email, use the attach method within the mailable class’ build method. The attach method accepts the full path to the file as its first argument:
public function build()
{
return $this->view('emails.orders.shipped')
->attach('/path/to/file');
}
public function build()
{
return $this->view('emails.orders.shipped')
->attach('/path/to/file', [
'as' => 'name.pdf',
'mime' => 'application/pdf',
]);
}
Raw Data Attachments
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 email without writing it to disk. The attachData method accepts the raw data bytes as its first argument, the name of the file as its second argument, and an array of options as its third argument:
public function build()
{
return $this->view('emails.orders.shipped')
->attachData($this->pdf, 'name.pdf', [
'mime' => 'application/pdf',
]);
}
namespace App\Http\Controllers;
use App\Order;
use App\Mail\OrderShipped;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;
use App\Http\Controllers\Controller;
class OrderController extends Controller
{
/**
* Ship the given order.
*
* @param Request $request
* @param int $orderId
* @return Response
*/
public function ship(Request $request, $orderId)
{
$order = Order::findOrFail($orderId);
// Ship order...
Mail::to($request->user())->send(new OrderShipped($order));
}
}
