Mail Configuration

Learn how to set up services for sending mail.

Driver Prerequisites
Mailgun driver
Postmark Driver
SES driver
Mail & Local Development
Log Driver
Universal To
Pretend Mail Mode

October CMS provides drivers for SMTP, Mailgun, SparkPost, Amazon SES and sendmail, allowing you to quickly get started sending mail through a local or cloud based service of your choice.

There are two ways to configure mail services, either using the admin panel via Settings → Mail Settings or by updating the default configuration values. In these examples we will update the file-based configuration values.

The mail settings screen in the admin panel will override the settings provided by the file-based configuration. Clicking the Reset to Default button will update the mail settings to the latest. If you do not click Save on this form, then the settings will continue to be sourced from the configuration files.

# Driver Prerequisites

In most cases you can use the SMTP driver and it will be supported by most mailing providers. However, using the API-based drivers are often a simpler and faster approach.

# Mailgun driver

To use the Mailgun driver, install Symfony's Mailgun Mailer transport via Composer.

composer require symfony/mailgun-mailer symfony/http-client

Next, 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',
    'endpoint' => 'api.mailgun.net', // api.eu.mailgun.net for EU
],

# Postmark Driver

To use the Postmark driver, install Symfony's Postmark Mailer transport via Composer.

composer require symfony/postmark-mailer symfony/http-client

Next, set the default option in your application's config/mail.php configuration file to postmark. After configuring your application's default mailer, verify that your config/services.php configuration file contains the following.

'postmark' => [
    'token' => env('POSTMARK_TOKEN'),
],

# SES driver

To use the Amazon SES driver you must first install the Amazon AWS SDK for PHP. You may install this library via the Composer package manager.

composer require aws/aws-sdk-php

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

# 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. There are 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 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@example.tld',
    'name' => 'Dev Example'
],

# Pretend Mail Mode

You can dynamically disable sending mail using the Mail::pretend method. When the mailer is in pretend mode, messages will be written to your application's log files instead of being sent to the recipient.

Mail::pretend();