Type Safety

Generate type-safe PHP code from your Lettr templates, so mistakes show up in your editor instead of in a sent email. The SDK provides three Artisan commands that connect to the Lettr API, read your templates and their merge tags, and generate PHP classes you can use in your application. Your IDE can then autocomplete template slugs, enforce required merge tags, and flag typos before you deploy.

This page describes lettr/lettr-laravel 2.7.0 and later. On 2.6.x the generated code looks different: DTO properties lose camelCase, Blade loops use $item->key, Mailables for Lettr templates set a subject, and none of the files carry a generated-file docblock. Upgrade with composer update lettr/lettr-laravel, then re-run the commands.

Why Code Generation?

Using string literals for template slugs and merge tags is error-prone:

// ❌ Typos only surface when the email goes out
Mail::lettr()->sendTemplate('welcom-email', 'Welcome!', ['frist_name' => 'John']);

With generated code, your IDE catches mistakes immediately:

// ✅ Type-safe, autocomplete-friendly
Mail::lettr()->sendTemplate(
    LettrTemplate::WelcomeEmail->value,
    'Welcome!',
    new WelcomeEmailData(firstName: 'John', activationUrl: $url),
);

The first example sends with a slug that doesn’t exist and a merge tag the template never reads. In the second, your IDE and static analysis flag both mistakes: LettrTemplate::WelcomEmail doesn’t exist, and WelcomeEmailData requires firstName and activationUrl.

Generate Everything at Once

The lettr:init command can generate all code for you during setup:

php artisan lettr:init

Or generate individually using the commands below.

Template Enum

Generate an enum containing all your template slugs:

php artisan lettr:generate-enum

This creates app/Enums/LettrTemplate.php:

<?php

declare(strict_types=1);

namespace App\Enums;

/**
 * Slugs of the templates in your Lettr account.
 *
 * Generated by `php artisan lettr:generate-enum`. Running it again
 * overwrites this file, so don't edit it by hand.
 */
enum LettrTemplate: string
{
    case WelcomeEmail = 'welcome-email';
    case OrderConfirmation = 'order-confirmation';
    case Template2faCode = '2fa-code';
    // ... all your templates
}

The command reads every template in your Lettr account (using the API key in your .env) and generates a backed enum case for each one. The case name is the PascalCase version of the template slug, adjusted when PHP wouldn’t accept it:

Slug	Case name	Why
`welcome-email`	`WelcomeEmail`	PascalCase of the slug
`2fa-code`	`Template2faCode`	A name can’t start with a digit, so it gets a `Template` prefix
`class`	`ClassTemplate`	`class` is reserved for enum cases, so it gets a `Template` suffix

Usage

use App\Enums\LettrTemplate;

// IDE autocomplete shows all available templates
Mail::lettr()
    ->to($user->email)
    ->sendTemplate(LettrTemplate::WelcomeEmail->value, 'Welcome!', $data);

Benefits

Autocomplete - Your IDE suggests available templates
Refactoring - Rename templates safely across your codebase
Discovery - See all templates without leaving your editor

Template DTOs

Generate data transfer objects for each template’s merge tags:

php artisan lettr:generate-dtos
php artisan lettr:generate-dtos --template=welcome-email   # One template
php artisan lettr:generate-dtos --dry-run                  # Preview without writing files

This creates a DTO for each template in app/Dto/Lettr/:

<?php

declare(strict_types=1);

namespace App\Dto\Lettr;

use Illuminate\Contracts\Support\Arrayable;

/**
 * Merge tags of the Lettr template `welcome-email`.
 *
 * Generated by `php artisan lettr:generate-dtos` or
 * `php artisan lettr:pull --with-mailables`. Running it again overwrites
 * this file, so don't edit it by hand.
 */
final readonly class WelcomeEmailData implements Arrayable
{
    public function __construct(
        public string $firstName,
        public string $activationUrl,
        public ?string $companyName = null,
    ) {}

    /**
     * @return array<string, mixed>
     */
    public function toArray(): array
    {
        return [
            'first_name' => $this->firstName,
            'activation_url' => $this->activationUrl,
            'company_name' => $this->companyName,
        ];
    }
}

The command reads each template’s merge tags from its active version and generates a readonly class with typed constructor parameters:

Required merge tags become required parameters and come first; optional ones default to null.
Property names are camelCase: first_name and FIRST_NAME become $firstName, and orderId stays $orderId. If two keys would end up with the same name (FIRST_NAME and first_name in one template), both keep their original key as the property name instead.
toArray() maps the properties back to the original merge tag keys. Optional values you leave out are sent as null.
Class names follow the same rules as enum cases, plus a Data suffix. PHP reserves more words for class names than for enum cases, so a template with the slug new gets NewTemplateData.

Templates without merge tags, or without an active version, are skipped and listed in the command output. --template with a slug that doesn’t exist exits with a failure code.

Loops

A loop block gets its own item DTO, and the parent takes an array of them:

final readonly class OrderConfirmationData implements Arrayable
{
    /**
     * @param  OrderConfirmationDataItemData[]  $items
     */
    public function __construct(
        public array $items,
    ) {}

    /**
     * @return array<string, mixed>
     */
    public function toArray(): array
    {
        return [
            'items' => array_map(fn (OrderConfirmationDataItemData $item) => $item->toArray(), $this->items),
        ];
    }
}

new OrderConfirmationData(items: [
    new OrderConfirmationDataItemData(name: 'Notebook', quantity: 2),
]);

If the loop merge tag is optional, you can leave it out and toArray() sends null for it.

Usage

sendTemplate() accepts the DTO directly, because it implements Arrayable:

use App\Dto\Lettr\WelcomeEmailData;

$data = new WelcomeEmailData(
    firstName: 'John',
    activationUrl: $url,
);

Mail::lettr()
    ->to($user->email)
    ->sendTemplate('welcome-email', 'Welcome!', $data);

Benefits

Required fields - Constructor enforces required merge tags
Type hints - Know exactly what data each template needs
Documentation - DTOs serve as living documentation

Combine DTOs with the template enum for maximum safety:

Mail::lettr()
    ->to($user->email)
    ->sendTemplate(LettrTemplate::WelcomeEmail->value, 'Welcome!', $data);

Mailable Classes

Generate a Mailable class, and a DTO for its merge tags, for each template:

php artisan lettr:pull --with-mailables

Mailables are created in app/Mail/Lettr/. What they send depends on how you pull:

Command	The Mailable sends	Subject
`lettr:pull --with-mailables`	The Blade view pulled to `resources/views/emails/lettr/`, rendered by your app	Generated from the template name. Edit it in `envelope()`
`lettr:pull --with-mailables --as-html` `lettr:pull --with-mailables --skip-templates`	The template stored in Lettr, by slug. Your app sends only the merge tag data	The subject set on the template in Lettr, unless you set one in `envelope()`

Lettr template Mailables

With --as-html or --skip-templates, the Mailable points at the template in Lettr. Editing the template in the dashboard changes the email without a deploy:

<?php

declare(strict_types=1);

namespace App\Mail\Lettr;

use App\Dto\Lettr\WelcomeEmailData;
use Illuminate\Mail\Mailables\Envelope;
use Lettr\Laravel\Mail\LettrMailable;

/**
 * Sends the Lettr template `welcome-email` through the Lettr API, with the
 * merge tags passed to the constructor.
 *
 * Generated by `php artisan lettr:pull --with-mailables`. Running it again
 * overwrites this file, so commit any changes you make here before pulling
 * again.
 */
class WelcomeEmail extends LettrMailable
{
    protected ?string $templateSlug = 'welcome-email';

    /**
     * Path to the local HTML template file (for preview/testing).
     */
    protected ?string $templateHtmlPath = 'resources/templates/lettr/welcome-email.html';

    /**
     * Create a new message instance.
     */
    public function __construct(
        public readonly WelcomeEmailData $data,
    ) {}

    /**
     * Get the message envelope.
     *
     * The subject comes from the template in Lettr. Set one here to override it.
     */
    public function envelope(): Envelope
    {
        return new Envelope;
    }

    /**
     * Get the merge tags for this mailable.
     *
     * @return array<string, mixed>
     */
    public function withMergeTags(): array
    {
        return $this->data->toArray();
    }
}

Blade Mailables

Without those flags, the template is saved as a Blade view and the Mailable renders it locally. LettrMailable passes whatever withMergeTags() returns — here the DTO’s toArray() — to the view. Loop items reach the view as arrays, so the pulled view reads them as $item['name'], and a loop you leave out renders nothing:

/**
 * Sends the Blade view `emails.lettr.welcome-email`, pulled from the Lettr
 * template `welcome-email` and rendered by your app.
 *
 * Generated by `php artisan lettr:pull --with-mailables`. Running it again
 * overwrites this file, so commit any changes you make here before pulling
 * again.
 */
class WelcomeEmail extends LettrMailable
{
    /**
     * The Blade view for this email.
     */
    protected ?string $bladeView = 'emails.lettr.welcome-email';

    /**
     * Create a new message instance.
     */
    public function __construct(
        public readonly WelcomeEmailData $data,
    ) {}

    /**
     * Get the message envelope.
     */
    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Welcome Email',
        );
    }

    /**
     * Get the merge tags for this mailable.
     *
     * @return array<string, mixed>
     */
    public function withMergeTags(): array
    {
        return $this->data->toArray();
    }
}

The view name comes from blade_path in config/lettr.php, so a custom path still resolves as long as it’s inside one of your view directories.

Usage

Either kind is sent like any other Mailable:

use App\Dto\Lettr\WelcomeEmailData;
use App\Mail\Lettr\WelcomeEmail;

Mail::to($user->email)->send(
    new WelcomeEmail(new WelcomeEmailData(
        firstName: $user->first_name,
        activationUrl: $url,
    ))
);

Re-running the Command

Every run rewrites all the files it generates: Blade views, HTML files, DTOs, Mailables and the enum. Files that already existed are marked with ↻ in the output, followed by a warning:

WARN  3 existing file(s) were overwritten (marked ↻). Any local changes to them are gone; check your version control if that wasn't intended.

If you’ve edited a generated Mailable (a from address, attachments, a custom subject), commit it first so you can bring the changes back, or run with --dry-run to see which files would be overwritten.

Benefits

Standard Laravel - Works with queues, events, and testing
Encapsulation - Template logic stays in one place
Familiar API - Same patterns you already use

Keeping Code in Sync

When you add or modify templates in Lettr, regenerate your code:

# Regenerate enum with new templates
php artisan lettr:generate-enum

# Regenerate DTOs with updated merge tags
php artisan lettr:generate-dtos

Every generated class has a docblock naming the command that generated it and saying the next run overwrites it. A Mailable for a template without merge tags has no constructor. The files follow Laravel’s code style, so Pint leaves them unchanged. Generated files are safe to commit to version control. They act as a snapshot of your templates at generation time. If a template is renamed or a merge tag is added in Lettr, the generated code won’t update automatically — run the commands again to pick up changes. Regenerating replaces the enum and DTOs. A DTO for a template that no longer has merge tags isn’t deleted, so remove it yourself.

Add these commands to your CI/CD pipeline to ensure code stays in sync with your templates. If the generated output differs from what’s committed, you know someone updated a template without regenerating.

Recommended Workflow

Create or update a template in the Lettr dashboard
Run php artisan lettr:generate-enum and php artisan lettr:generate-dtos
Commit the generated files
Use the enum and DTO in your application code

Configuration

Customize paths and names in config/lettr.php:

'templates' => [
    'html_path' => resource_path('templates/lettr'),
    'blade_path' => resource_path('views/emails/lettr'),

    'enum_path' => app_path('Enums'),
    'enum_namespace' => 'App\\Enums',
    'enum_class' => 'LettrTemplate',

    'dto_path' => app_path('Dto/Lettr'),
    'dto_namespace' => 'App\\Dto\\Lettr',

    'mailable_path' => app_path('Mail/Lettr'),
    'mailable_namespace' => 'App\\Mail\\Lettr',
],

Option	Default	Description
`html_path`	`resources/templates/lettr`	Directory for HTML files from `lettr:pull --as-html`
`blade_path`	`resources/views/emails/lettr`	Directory for Blade views from `lettr:pull`. Keep it inside a view directory so Blade Mailables can find their views
`enum_path`	`app/Enums`	Directory for the generated enum file
`enum_namespace`	`App\Enums`	PHP namespace for the enum
`enum_class`	`LettrTemplate`	Class name for the generated enum
`dto_path`	`app/Dto/Lettr`	Directory for generated DTO files
`dto_namespace`	`App\Dto\Lettr`	PHP namespace for DTOs
`mailable_path`	`app/Mail/Lettr`	Directory for generated Mailable files
`mailable_namespace`	`App\Mail\Lettr`	PHP namespace for Mailables

Paths can be absolute or relative to your project root. Any key you leave out of a published config/lettr.php falls back to its default. Each namespace has to match its path under the autoload.psr-4 section of your composer.json, or the generated classes won’t load. The commands warn when they don’t match:

WARN  App\Data\Lettr\WelcomeEmailData won't autoload from app/Dto/Lettr/WelcomeEmailData.php. Check that the namespace and path in config/lettr.php match the PSR-4 autoload section of composer.json.

Artisan Commands Reference

Command	What It Generates	Output Location
`lettr:init`	Enum, DTOs and Mailables (interactive)	Configured paths
`lettr:generate-enum`	Template slug enum	`app/Enums/LettrTemplate.php`
`lettr:generate-dtos`	Merge tag DTOs	`app/Dto/Lettr/`
`lettr:pull --with-mailables`	Blade views, DTOs and Mailables	`resources/views/emails/lettr/`, `app/Dto/Lettr/`, `app/Mail/Lettr/`

Option	Commands	Description
`--dry-run`	all three	Preview what would be generated without writing files
`--template=`	`lettr:pull`, `lettr:generate-dtos`	Only one template, by slug. Exits with a failure code if it doesn’t exist
`--with-mailables`	`lettr:pull`	Also generate Mailables and DTOs
`--as-html`	`lettr:pull`	Save raw HTML, and generate Mailables that send the Lettr template
`--skip-templates`	`lettr:pull`	Don’t download templates; with `--with-mailables`, generate DTOs and Mailables that send the Lettr template

What’s Next

Sending Emails

Put your generated code to use

Templates

Template versioning, projects, and sync commands

API Reference

Complete REST API documentation

Best Practices

Sending best practices and deliverability tips

Documentation

Quickstart

Learn

Integrations

Resources

Why Code Generation?

Generate Everything at Once

Template Enum

Usage

Benefits

Template DTOs

Loops

Usage

Benefits

Mailable Classes

Lettr template Mailables

Blade Mailables

Usage

Re-running the Command

Benefits

Keeping Code in Sync

Recommended Workflow

Configuration

Artisan Commands Reference

What’s Next

Sending Emails

Templates

API Reference

Best Practices

​Why Code Generation?

​Generate Everything at Once

​Template Enum

​Usage

​Benefits

​Template DTOs

​Loops

​Usage

​Benefits

​Mailable Classes

​Lettr template Mailables

​Blade Mailables

​Usage

​Re-running the Command

​Benefits

​Keeping Code in Sync

​Recommended Workflow

​Configuration

​Artisan Commands Reference

​What’s Next

Sending Emails

Templates

API Reference

Best Practices

Why Code Generation?

Generate Everything at Once

Template Enum

Usage

Benefits

Template DTOs

Loops

Usage

Benefits

Mailable Classes

Lettr template Mailables

Blade Mailables

Usage

Re-running the Command

Benefits

Keeping Code in Sync

Recommended Workflow

Configuration

Artisan Commands Reference

What’s Next