How Laravel Selects and Configures Mail Transports

Laravel sends outgoing mail through a mailer, a named configuration entry that tells it how to send a message. The mailer selects a transport, the method Laravel uses to deliver the message, such as SMTP or a log. SMTP (Simple Mail Transfer Protocol) sends mail by connecting to a mail server.

The selection starts with the configured default mailer, then uses that mailer’s transport and connection settings. In the Laravel 13.x application skeleton, MAIL_MAILER names the default mailer and falls back to log. Setting SMTP credentials alone does not select SMTP. To troubleshoot mail, trace which mailer Laravel chose, identify its transport, then check that transport’s settings.

Laravel selects a mailer, then a transport

Laravel first chooses a mailer name. Unless the sending code specifies a mailer, Laravel uses the default configured in config/mail.php. In the 13.x skeleton, that value comes from MAIL_MAILER; its fallback, log, writes messages to a log instead of delivering them through an SMTP server.

Laravel then finds the matching entry in the mailers configuration array. An entry named smtp uses SMTP when its transport value is smtp; Laravel uses the name to find the entry and the value to choose the delivery method. Laravel’s 13.x mail configuration shows this mapping, and the framework’s MailManager finds and reads the named entry. If the requested name has no matching configuration, Laravel throws an exception rather than guessing a transport.

For example, setting MAIL_MAILER=smtp selects the configured smtp entry. To use a different configured mailer for a particular message, code can call Mail::mailer('name'), as described in Laravel’s mail documentation. Laravel also supports composite mailers: a configured failover mailer tries another mailer when its primary option is unavailable, while roundrobin distributes messages across configured mailers. Defining several mailers does not activate either behavior; the selected configuration must specify it.

Laravel caches resolved mailers inside the manager. In a long-running process, the manager may keep using a mailer it created before configuration values changed. If a runtime change has no effect, check whether the process needs to reload its configuration or restart.

SMTP settings define the connection

Once Laravel selects an SMTP mailer, its configuration supplies the details for connecting to the mail server. The Laravel 13.x skeleton maps environment variables to connection settings. The scheme specifies how Laravel makes the SMTP connection. Separate fields provide the host and port, along with the username and password. It also accepts MAIL_URL, which Laravel reads to set mailer configuration. If both a URL and separate fields are set, inspect the resulting configuration rather than assuming the values act independently.

A basic example for a 13.x project whose smtp entry uses these fields is:

MAIL_MAILER=smtp
MAIL_SCHEME=smtp
MAIL_HOST=mail.example.test
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_FROM_ADDRESS=notifications@example.test
MAIL_FROM_NAME="${APP_NAME}"

Replace the host and credentials with the details supplied by your mail provider. This example shows how Laravel’s settings work together, but each mail provider sets its own connection requirements. Confirm the provider’s host, port, and security requirements, and check the project’s config/mail.php.

In the cited 13.x framework source, Laravel uses smtps by default when the port is 465, and smtp for other ports, if no scheme is configured. An explicit MAIL_SCHEME supplies the scheme instead. The SMTP transport builds its connection from the configured host, port, and credentials.

The skeleton’s MAIL_EHLO_DOMAIN sets the local domain Laravel presents when identifying itself to the SMTP server. If that variable is unset, the shown configuration derives the value from the host in APP_URL, falling back to localhost. This setting describes the sending client’s identity during the SMTP exchange; it is separate from MAIL_HOST, which names the mail server.

Environment variables control different parts of sending

The following variables are mapped in the Laravel 13.x application skeleton’s config/mail.php. Defaults and mappings can differ in older or customized projects.

The sender variables do not configure the SMTP connection. They set the default identity shown on outgoing messages. The MAIL_LOG_CHANNEL and MAIL_SENDMAIL_PATH variables matter only when the selected mailer uses the corresponding transport.

Check the project’s configuration before applying instructions written for another Laravel version. The 13.x skeleton uses MAIL_SCHEME and does not map MAIL_ENCRYPTION in its SMTP entry. Laravel also records the older rename from MAIL_DRIVER to MAIL_MAILER in its 7.x upgrade guide. These differences make the project’s config/mail.php the clearest reference for which environment variables actually affect its mailers.

Check configuration when settings appear ignored

Laravel reads environment values through configuration files. After you run config:cache, Laravel does not load .env during requests or Artisan commands. Code should read values through Laravel’s configuration system. If an edited .env value has no effect, check whether the deployed configuration cache still contains the old value. Laravel’s configuration documentation covers configuration caching and environment variables.

Keep mail credentials out of source control. Laravel warns that committing .env can expose secrets, and server-level environment variables can override values in that file. When troubleshooting, verify both which mailer the sending code selected and which values the deployed configuration supplies to that mailer.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com