Installation

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, 12.x, or 13.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

Option 1: Interactive Setup (Recommended)

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

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.

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.

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.

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.

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

Option	Description
`api_key`	Your Lettr API key. Always set via the `LETTR_API_KEY` environment variable — never hardcode it.
`default_project_id`	The default project to use when pulling/pushing templates. Can be overridden per-request.
`templates.html_path`	Where `lettr:pull --as-html` saves raw HTML template files.
`templates.blade_path`	Where `lettr:pull` saves Blade template files.
`templates.mailable_path`	Where `lettr:pull --with-mailables` generates Mailable classes.
`templates.mailable_namespace`	PHP namespace for generated Mailable classes.
`templates.dto_path`	Where `lettr:generate-dtos` creates DTO classes.
`templates.dto_namespace`	PHP namespace for generated DTOs.
`templates.enum_path`	Where `lettr:generate-enum` creates the template enum.
`templates.enum_namespace`	PHP namespace for the generated enum.
`templates.enum_class`	Class 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

API key not recognized

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.

Class not found errors

Run composer dump-autoload to regenerate the autoloader. If you’re using Laravel’s config cache, run php artisan config:clear as well.

Domain verification errors when sending

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.

Emails not arriving

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.

Documentation

Quickstart

Learn

Integrations

Resources

Installation

Requirements

Install the Package

Configuration

Option 1: Interactive Setup (Recommended)

Option 2: Manual Setup

Configuration Options

Verify Installation

Troubleshooting

What’s Next

Sending Emails

Templates

​Requirements

​Install the Package

​Configuration

​Option 1: Interactive Setup (Recommended)

​Option 2: Manual Setup

​Configuration Options

​Verify Installation

​Troubleshooting

​What’s Next

Sending Emails

Templates

Requirements

Install the Package

Configuration

Option 1: Interactive Setup (Recommended)

Option 2: Manual Setup

Configuration Options

Verify Installation

Troubleshooting

What’s Next