Skip to main content
Configure Laravel to send emails through Lettr using SMTP. This approach works with Laravel’s built-in mail system — no package installation required, just update your environment variables.
If you prefer a tighter integration with template support and code generation, check out the Laravel SDK instead. The SDK integrates directly with Laravel’s mail transport while adding type-safe template features.

​
Prerequisites

Before you begin, make sure you have:

API Key

Create an API key in the Lettr dashboard

Verified Domain

Add and verify your sending domain
You’ll also need:
  • Laravel 10.x, 11.x, or 12.x installed
  • A MAIL_FROM_ADDRESS that uses your verified sending domain

​
Configuration

1

Update your .env file

Add the following SMTP settings to your .env file:
MAIL_MAILER=smtp
MAIL_HOST=smtp.lettr.com
MAIL_PORT=587
MAIL_USERNAME=lettr
MAIL_PASSWORD=lttr_your_api_key_here
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=you@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"
Replace lttr_your_api_key_here with your actual Lettr API key. Your API key is your SMTP password.
2

Verify config/mail.php

Ensure your config/mail.php has the SMTP mailer configured. Laravel ships with this by default:
'default' => env('MAIL_MAILER', 'smtp'),

'mailers' => [
    'smtp' => [
        'transport' => 'smtp',
        'host' => env('MAIL_HOST', 'smtp.mailgun.org'),
        'port' => env('MAIL_PORT', 587),
        'encryption' => env('MAIL_ENCRYPTION', 'tls'),
        'username' => env('MAIL_USERNAME'),
        'password' => env('MAIL_PASSWORD'),
        'timeout' => null,
        'local_domain' => env('MAIL_EHLO_DOMAIN'),
    ],
    // ...
],
No changes needed — the environment variables from .env will be automatically loaded.
3

Clear configuration cache

After updating your .env file, clear Laravel’s configuration cache:
php artisan config:clear
This ensures Laravel picks up your new SMTP settings.

​
Sending Emails

Once configured, send emails using Laravel’s Mail facade exactly as you normally would:

​
Using Mailables

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

Mail::to('user@example.com')->send(new WelcomeEmail($user));

​
Using Mail::raw()

For simple text emails without a Mailable class: 
use Illuminate\Support\Facades\Mail;

Mail::raw('This is a plain text email.', function ($message) {
    $message->to('recipient@example.com')
            ->subject('Hello from Lettr');
});

​
Using Mail::html()

For HTML emails without a Mailable class: 
use Illuminate\Support\Facades\Mail;

Mail::html('<h1>Hello!</h1><p>This is an HTML email.</p>', function ($message) {
    $message->to('recipient@example.com')
            ->subject('HTML Email');
});

​
Testing Your Setup

​
Quick Test with Tinker

Send a test email using Tinker to verify your SMTP configuration: 
php artisan tinker

Mail::raw('Test email from Lettr via SMTP', function ($message) {
    $message->to('your-email@example.com')
            ->subject('SMTP Test Email');
});
If the command succeeds without errors, check your inbox. The email should arrive within a few seconds.

​
Test with a Real Mailable

Create a test Mailable: 
php artisan make:mail TestEmail
Update app/Mail/TestEmail.php: 
<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class TestEmail extends Mailable
{
    use Queueable, SerializesModels;

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Test Email from Lettr',
        );
    }

    public function content(): Content
    {
        return new Content(
            view: 'emails.test',
        );
    }
}
Create the view at resources/views/emails/test.blade.php: 
<!DOCTYPE html>
<html>
<head>
    <title>Test Email</title>
</head>
<body>
    <h1>Hello from Lettr!</h1>
    <p>If you're seeing this, your Laravel SMTP configuration is working correctly.</p>
</body>
</html>
Send the test email: 
use App\Mail\TestEmail;
use Illuminate\Support\Facades\Mail;

Mail::to('your-email@example.com')->send(new TestEmail());

​
Port Options

Lettr supports multiple SMTP ports. If port 587 doesn’t work for your environment, try these alternatives:
PortEncryptionConfiguration
587STARTTLS (recommended)MAIL_PORT=587 MAIL_ENCRYPTION=tls
465Implicit TLSMAIL_PORT=465 MAIL_ENCRYPTION=ssl
2465Implicit TLS (alternate)MAIL_PORT=2465 MAIL_ENCRYPTION=ssl
2587STARTTLS (alternate)MAIL_PORT=2587 MAIL_ENCRYPTION=tls
Port 465 uses implicit SSL/TLS, which establishes a secure connection immediately. Port 587 uses explicit STARTTLS, which upgrades an unencrypted connection. Both are secure.

​
Multiple Mailers

If you need to use both Lettr and another email provider (e.g., for different email types), configure multiple mailers: 
// config/mail.php
'mailers' => [
    'smtp' => [
        'transport' => 'smtp',
        'host' => env('MAIL_HOST'),
        // ... default mailer (Lettr)
    ],

    'lettr' => [
        'transport' => 'smtp',
        'host' => 'smtp.lettr.com',
        'port' => 587,
        'encryption' => 'tls',
        'username' => 'lettr',
        'password' => env('LETTR_API_KEY'),
    ],

    'backup' => [
        'transport' => 'smtp',
        'host' => env('BACKUP_MAIL_HOST'),
        // ... backup provider
    ],
],
Send using a specific mailer: 
Mail::mailer('lettr')
    ->to('user@example.com')
    ->send(new WelcomeEmail());

​
Error Handling

Wrap your mail sending in try-catch blocks to handle SMTP errors: 
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Log;

try {
    Mail::to('user@example.com')->send(new WelcomeEmail());
} catch (\Exception $e) {
    Log::error('Failed to send email: ' . $e->getMessage());

    // Handle the error (retry, alert admin, etc.)
}

​
Troubleshooting

Check your API key is correct and starts with lttr_. Verify the username is exactly lettr (lowercase). Run php artisan config:clear to clear cached configuration.
Your firewall may be blocking outbound SMTP connections. Try alternate ports (465, 2465, or 2587). Verify smtp.lettr.com resolves correctly.
Ensure your MAIL_FROM_ADDRESS domain is verified in the Lettr dashboard. See Domain Verification for help.
Check your Lettr logs to see if the API accepted the request. If accepted but not delivered, see Delivery Issues.
Enable Laravel’s mail debug logging in .env:
MAIL_LOG_CHANNEL=stack
LOG_CHANNEL=stack
This logs all outgoing emails to storage/logs/laravel.log.For testing without sending real emails, use the log mailer:
MAIL_MAILER=log

​
What’s Next

Laravel SDK

Upgrade to the Laravel SDK for template support

Sending Best Practices

Improve deliverability and engagement

Templates

Create reusable email templates

Troubleshooting

Fix common delivery issues