Skip to main content
This page covers installing the lettr/lettr-laravel Composer package and configuring it to send emails through Lettr. If you haven’t already, start with the Introduction for a quick overview of what the SDK provides.

​
Requirements

  • PHP 8.4 or higher
  • Laravel 10.x, 11.x, or 12.x

​
Install the Package

composer require lettr/lettr-laravel
The package uses Laravel’s auto-discovery, so the service provider registers automatically. No manual provider registration is needed.

​
Configuration

Run the init command for guided configuration: 
php artisan lettr:init
This handles all the steps below automatically. The command walks you through each setting interactively, so you don’t need to edit config files by hand. If you want full control over each step, use the manual setup below.

​
Option 2: Manual Setup

1

Add your API key

Add your Lettr API key to .env:
LETTR_API_KEY=lttr_xxxxxxxxxxxx
Get your API key from the Lettr dashboard. API keys use the lttr_ prefix followed by 64 hexadecimal characters. See API Keys for details on creating and managing keys.
2

Publish the config file

php artisan vendor:publish --tag=lettr-config
This creates config/lettr.php with customizable options. See Configuration Options below for a full reference of available settings.
3

Add the Lettr mailer

Add the Lettr mailer to config/mail.php:
config/mail.php
'mailers' => [
    // ... other mailers

    'lettr' => [
        'transport' => 'lettr',
    ],
],
This registers Lettr as an available mailer in Laravel’s mail system. You can use it alongside other mailers (e.g., smtp, log, ses) and choose per-email which one to use.
4

Configure sender address

Set your default sender address in .env. The address must use a verified sending domain:
MAIL_FROM_ADDRESS=hello@yourdomain.com
MAIL_FROM_NAME="Your App Name"
The sender domain must be verified in your Lettr dashboard before you can send emails. If you try to send from an unverified domain, the API will return a 422 error. See Sending Domains for setup instructions.
5

Set as default mailer (optional)

To use Lettr as your default mailer, update .env:
MAIL_MAILER=lettr
Or keep your current mailer and use Lettr explicitly when needed:
Mail::mailer('lettr')->to($user)->send(new WelcomeMail());
During development, you may want to keep MAIL_MAILER=log to avoid sending real emails. Switch to lettr in staging and production.

​
Configuration Options

The config/lettr.php file contains these options:
config/lettr.php
return [
    // Your Lettr API key
    'api_key' => env('LETTR_API_KEY'),

    // Paths for generated files
    'templates' => [
        'html_path' => resource_path('templates/lettr'),
        'blade_path' => resource_path('views/emails/lettr'),
        'mailable_path' => app_path('Mail/Lettr'),
        'mailable_namespace' => 'App\\Mail\\Lettr',
        'dto_path' => app_path('Dto/Lettr'),
        'dto_namespace' => 'App\\Dto\\Lettr',
        'enum_path' => app_path('Enums'),
        'enum_namespace' => 'App\\Enums',
        'enum_class' => 'LettrTemplate',
    ],
];
OptionDescription
api_keyYour Lettr API key. Always set via the LETTR_API_KEY environment variable — never hardcode it.
default_project_idThe default project to use when pulling/pushing templates. Can be overridden per-request.
templates.html_pathWhere lettr:pull --as-html saves raw HTML template files.
templates.blade_pathWhere lettr:pull saves Blade template files.
templates.mailable_pathWhere lettr:pull --with-mailables generates Mailable classes.
templates.mailable_namespacePHP namespace for generated Mailable classes.
templates.dto_pathWhere lettr:generate-dtos creates DTO classes.
templates.dto_namespacePHP namespace for generated DTOs.
templates.enum_pathWhere lettr:generate-enum creates the template enum.
templates.enum_namespacePHP namespace for the generated enum.
templates.enum_classClass name for the generated template enum.

​
Verify Installation

Run the check command to verify your installation: 
php artisan lettr:check
This validates your API key and configuration. If everything is set up correctly, you’ll see a success message.

​
Troubleshooting

Make sure your .env file contains LETTR_API_KEY with the lttr_ prefix. Run php artisan config:clear to clear any cached configuration, then try again.
Run composer dump-autoload to regenerate the autoloader. If you’re using Laravel’s config cache, run php artisan config:clear as well.
The from address must use a domain that is verified in your Lettr dashboard. Check that your MAIL_FROM_ADDRESS in .env matches a verified sending domain. See Domain Verification for common issues.
Check your Lettr logs to see if the API accepted the request. If the email was accepted but not delivered, see Delivery Issues for diagnosis steps.

​
What’s Next

Sending Emails

Learn the different ways to send emails through Lettr

Templates

Work with Lettr-managed templates and merge tags