Laravel SMTP Settings: .env and mail.php

Before you start

Tick off what you already have. New to tinyRelay? See how onboarding works.

0 of 4 in placeTap each one you already have.

A tinyRelay accountSet up by our team during onboarding.SMTP credentialsA username and password, plus the [SMTP host], [port] and [encryption] to use, all issued at onboarding.A DKIM-signed sender domainSet up with tinyRelay, with the CNAME tec1._domainkey.yourdomain.com pointing to tec1.dkim.tinyemail.com.A Laravel appIts config/mail.php defines an smtp mailer. The default skeleton does.

SMTP host, port and encryption are issued at onboarding. This guide shows them as [SMTP host], [port] and [encryption]. Whether SMTP sends receive the same webhooks and metadata as API sends is being confirmed.

Configure Laravel mail for the SMTP relay

Laravel reads mail settings from .env through config/mail.php. You change the environment, not your code.

1. Add the credentials to .env

Pick the tab that matches your config/mail.php. Current skeletons read MAIL_SCHEME; older ones read MAIL_ENCRYPTION.

.env

MAIL_SCHEME MAIL_ENCRYPTION

Copy

MAIL_MAILER=smtp
# Issued at onboarding
MAIL_HOST="[SMTP host]"
MAIL_PORT="[port]"
# smtp = STARTTLS, smtps = implicit TLS: match the [encryption] you were given
MAIL_SCHEME="[smtp or smtps]"
MAIL_USERNAME="[SMTP username]"
MAIL_PASSWORD="[SMTP password]"
MAIL_FROM_ADDRESS="no-reply@acme.com"
MAIL_FROM_NAME="${APP_NAME}"

MAIL_MAILER=smtp
# Issued at onboarding
MAIL_HOST="[SMTP host]"
MAIL_PORT="[port]"
MAIL_ENCRYPTION="[encryption]"
MAIL_USERNAME="[SMTP username]"
MAIL_PASSWORD="[SMTP password]"
MAIL_FROM_ADDRESS="no-reply@acme.com"
MAIL_FROM_NAME="${APP_NAME}"

For MAIL_SCHEME: use smtp when the [encryption] you were given is STARTTLS, and smtps when it is implicit TLS.

2. Check config/mail.php

config/mail.php

'scheme' key 'encryption' key

Copy

// config/mail.php (current skeleton: no edits needed)
'default' => env('MAIL_MAILER', 'log'),

'mailers' => [
    'smtp' => [
        'transport' => 'smtp',
        'scheme' => env('MAIL_SCHEME'),
        'url' => env('MAIL_URL'),
        'host' => env('MAIL_HOST', '127.0.0.1'),
        'port' => env('MAIL_PORT', 2525),
        'username' => env('MAIL_USERNAME'),
        'password' => env('MAIL_PASSWORD'),
        'timeout' => null,
        'local_domain' => env('MAIL_EHLO_DOMAIN', parse_url((string) env('APP_URL', 'http://localhost'), PHP_URL_HOST)),
    ],
    // ...
],

'from' => [
    'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'),
    'name' => env('MAIL_FROM_NAME', env('APP_NAME', 'Laravel')),
],

// config/mail.php (older skeletons use an 'encryption' key; defaults omitted)
'mailers' => [
    'smtp' => [
        'transport' => 'smtp',
        'host' => env('MAIL_HOST'),
        'port' => env('MAIL_PORT'),
        'encryption' => env('MAIL_ENCRYPTION'),
        'username' => env('MAIL_USERNAME'),
        'password' => env('MAIL_PASSWORD'),
        'timeout' => null,
    ],
    // ...
],

3. Clear cached config

If you have run php artisan config:cache, Laravel ignores .env until you clear or rebuild the cache.

TerminalCopy

php artisan config:clear

4. Send a test email

Send one message to an inbox you control before switching production traffic.

TerminalCopy

php artisan tinker

> Mail::raw('tinyRelay SMTP test', fn ($m) => $m->to('you@example.com')->subject('SMTP test'));

Send Laravel mail through the SMTP relay

Nothing else changes. Mailables, notifications and queued mail all go through the default mailer.

app/Http/Controllers/OrderController.phpCopy

use App\Mail\OrderShipped;
use Illuminate\Support\Facades\Mail;

// Send now
Mail::to($request->user())->send(new OrderShipped($order));

// Or queue it so the web request does not wait on SMTP
Mail::to($request->user())->queue(new OrderShipped($order));

Keep the password out of version control

.env should not be committed. In production, set the same MAIL_* variables in your host's secret store. If you use the REST API from PHP as well, see send email with PHP.

Delivery events and the REST API

Documented

REST API sends

tinyRelay posts signed webhook events (SEND, DELIVERED, BOUNCED, OPEN, CLICK, UNSUBSCRIBE and SPAM) with your metadata on each one.

Being confirmed

SMTP sends

Whether SMTP sends receive the same webhooks and metadata is being confirmed, and this guide will be updated when it is.

If you need your own IDs echoed on every event today, send those messages through the API instead: see the transactional email API and email webhooks.

Troubleshooting

What do you see?5 common symptoms

Authentication failed Connection timed out or refused TLS or SSL handshake error Sender address rejected Accepted but never arrives

Authentication failedWhat to check

The username or password does not match what was issued at onboarding. Copy them again and check for stray quotes or spaces in your environment file.

Connection timed out or refusedWhat to check

Check [SMTP host] and [port]. Some hosting providers block outbound SMTP ports; ask yours if a correct host and port still time out.

TLS or SSL handshake errorWhat to check

The encryption mode does not match the port. STARTTLS and implicit TLS are different settings; use the [encryption] you were given.

Sender address rejectedWhat to check

Send from an address on a domain that was set up with tinyRelay during onboarding.

Accepted but never arrivesWhat to check

Check the DKIM CNAME on your sender domain, then the recipient address. The email bounce codes reference explains each bounce category.

FAQ

What SMTP host and port does tinyRelay use?

They are issued at onboarding together with your SMTP username and password, so they are shown here as placeholders. Use exactly the values you were given.

Should I set MAIL_SCHEME or MAIL_ENCRYPTION?

Check config/mail.php. If the smtp mailer has a scheme key, set MAIL_SCHEME to smtp for STARTTLS or smtps for implicit TLS. If it has an encryption key, set MAIL_ENCRYPTION.

Why does Laravel ignore my new .env values?

Your configuration is probably cached. Run php artisan config:clear, or rebuild the cache with php artisan config:cache.

Do Laravel emails sent over SMTP get tinyRelay webhooks?

This is being confirmed. Email sent through the REST API gets signed webhook events with your metadata; this guide will be updated for SMTP.

Laravel SMTP settings for tinyRelay

Before you start

Configure Laravel mail for the SMTP relay

1. Add the credentials to .env

2. Check config/mail.php

3. Clear cached config

4. Send a test email

Send Laravel mail through the SMTP relay

Keep the password out of version control

Delivery events and the REST API

Troubleshooting

FAQ

Next steps

Sources

Send transactional email with a service that reports back.