> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Install the lettr/lettr-laravel Composer package and configure it to send emails through Lettr, via guided or manual setup
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](/quickstart/laravel/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
```bash theme={null}
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:
```bash theme={null}
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 Lettr API key to `.env`:
```env theme={null}
LETTR_API_KEY=lttr_xxxxxxxxxxxx
```
Get your API key from the [Lettr dashboard](https://app.lettr.com/api-keys). API keys use the `lttr_` prefix followed by 64 hexadecimal characters. See [API Keys](/learn/api-keys/introduction) for details on creating and managing keys.
```bash theme={null}
php artisan vendor:publish --tag=lettr-config
```
This creates `config/lettr.php` with customizable options. See [Configuration Options](#configuration-options) below for a full reference of available settings.
Add the Lettr mailer to `config/mail.php`:
```php config/mail.php theme={null}
'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.
Set your default sender address in `.env`. The address must use a verified sending domain:
```env theme={null}
MAIL_FROM_ADDRESS=hello@yourdomain.com
MAIL_FROM_NAME="Your App Name"
```
The sender domain must be verified in your [Lettr dashboard](https://app.lettr.com/domains) before you can send emails. If you try to send from an unverified domain, the API will return a `422` error. See [Sending Domains](/learn/domains/sending-domains) for setup instructions.
To use Lettr as your default mailer, update `.env`:
```env theme={null}
MAIL_MAILER=lettr
```
Or keep your current mailer and use Lettr explicitly when needed:
```php theme={null}
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:
```php config/lettr.php theme={null}
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](/learn/templates/projects) 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:
```bash theme={null}
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](https://app.lettr.com/domains). Check that your `MAIL_FROM_ADDRESS` in `.env` matches a verified sending domain. See [Domain Verification](/knowledge-base/troubleshooting/domain-verification) for common issues.
Check your [Lettr logs](https://app.lettr.com/logs) to see if the API accepted the request. If the email was accepted but not delivered, see [Delivery Issues](/knowledge-base/troubleshooting/delivery-issues) for diagnosis steps.
## What's Next
Learn the different ways to send emails through Lettr
Work with Lettr-managed templates and merge tags