# Laravel
## 1. Installation
Install the package via Composer:
```bash
composer require lettermint/lettermint-laravel
```
Publish the configuration file:
```bash
php artisan vendor:publish --tag="lettermint-config"
```
:::note
Requires PHP 8.2+ and Laravel 9+.
:::
## 2. Configuration
### Environment Variables
Add your Lettermint credentials to `.env`:
```env title=".env"
LETTERMINT_TOKEN=your-api-token
LETTERMINT_ROUTE_ID=your-route-id
```
### Services Configuration
Add to `config/services.php`:
```php title="config/services.php"
'lettermint' => [
'token' => env('LETTERMINT_TOKEN'),
],
```
### Mail Configuration
Add the Lettermint mailer to `config/mail.php`:
```php title="config/mail.php"
'mailers' => [
// ... other mailers
'lettermint' => [
'transport' => 'lettermint',
'route_id' => env('LETTERMINT_ROUTE_ID'),
'idempotency' => true,
'idempotency_window' => 86400,
],
],
```
Set Lettermint as your default mailer in `.env`:
```env title=".env"
MAIL_MAILER=lettermint
```
## 3. Send Your First Email
Send emails using Laravel's standard Mail facade:
```php
use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;
Mail::to('recipient@example.com')->send(new WelcomeEmail($user));
```
Or specify the mailer explicitly:
```php
Mail::mailer('lettermint')->to('recipient@example.com')->send(new WelcomeEmail($user));
```
## 4. Tags
Categorize emails for filtering and analytics in your Lettermint dashboard.
### Using the tag() Method
```php
Mail::to('recipient@example.com')
->send((new WelcomeEmail($user))->tag('onboarding'));
```
### In Mailable Envelope
```php
use Illuminate\Mail\Mailables\Envelope;
public function envelope(): Envelope
{
return new Envelope(
subject: 'Welcome to Our Platform',
tags: ['onboarding'],
);
}
```
:::note
One tag per message. Tags can contain letters, numbers, hyphens, underscores, and spaces (max 255 characters).
See [Tags documentation](/platform/emails/tags) for more details.
:::
## 5. Metadata
Attach custom data for tracking and webhook payloads.
### Using the metadata() Method
```php
Mail::to('customer@example.com')
->send(
(new OrderConfirmation($order))
->metadata('order_id', $order->id)
->metadata('customer_id', $order->customer_id)
);
```
### In Mailable Envelope
```php
use Illuminate\Mail\Mailables\Envelope;
public function envelope(): Envelope
{
return new Envelope(
subject: 'Order Confirmation',
metadata: [
'order_id' => $this->order->id,
'customer_id' => $this->order->customer_id,
'order_total' => $this->order->total,
],
);
}
```
:::note
Metadata is included in webhook payloads but not sent to recipients.
:::
## 6. Multiple Routes
Configure separate mailers for different email types (transactional, marketing, etc.):
```php title="config/mail.php"
'mailers' => [
'lettermint_transactional' => [
'transport' => 'lettermint',
'route_id' => env('LETTERMINT_TRANSACTIONAL_ROUTE_ID'),
],
'lettermint_marketing' => [
'transport' => 'lettermint',
'route_id' => env('LETTERMINT_MARKETING_ROUTE_ID'),
],
],
```
```env title=".env"
LETTERMINT_TRANSACTIONAL_ROUTE_ID=your-transactional-route-id
LETTERMINT_MARKETING_ROUTE_ID=your-marketing-route-id
```
Send to specific routes:
```php
// Transactional emails (password resets, order confirmations)
Mail::mailer('lettermint_transactional')
->to($user)
->send(new PasswordResetEmail());
// Marketing emails (newsletters, promotions)
Mail::mailer('lettermint_marketing')
->to($user)
->send(new NewsletterEmail());
```
## 7. Idempotency
Prevent duplicate emails when retrying failed requests.
### Configuration
```php title="config/mail.php"
'lettermint' => [
'transport' => 'lettermint',
'idempotency' => true, // Enable automatic deduplication
'idempotency_window' => 86400, // Window in seconds (24 hours)
],
```
### Custom Idempotency Key
Override the automatic key for specific emails:
```php
use Illuminate\Mail\Mailables\Headers;
public function headers(): Headers
{
return new Headers(
text: [
'Idempotency-Key' => "welcome-{$this->user->id}",
],
);
}
```
:::tip
Set `idempotency_window` to 86400 or higher for permanent deduplication within API retention.
:::
## 8. Webhooks
The driver automatically registers a webhook endpoint and dispatches Laravel events.
### Configuration
```env title=".env"
LETTERMINT_WEBHOOK_SECRET=your-webhook-signing-secret
LETTERMINT_WEBHOOK_PREFIX=lettermint
LETTERMINT_WEBHOOK_TOLERANCE=300
```
The webhook endpoint is available at `POST /{prefix}/webhook` (default: `/lettermint/webhook`).
### Available Events
| Event Class | Trigger |
|-------------|---------|
| `MessageCreated` | Email accepted for processing |
| `MessageSent` | Email sent to recipient server |
| `MessageDelivered` | Email successfully delivered |
| `MessageHardBounced` | Permanent delivery failure |
| `MessageSpamComplaint` | Recipient marked as spam |
### Listening to Events
```php title="app/Providers/EventServiceProvider.php"
use Lettermint\Laravel\Events\MessageDelivered;
use Lettermint\Laravel\Events\MessageHardBounced;
protected $listen = [
MessageDelivered::class => [
\App\Listeners\HandleEmailDelivered::class,
],
MessageHardBounced::class => [
\App\Listeners\HandleEmailBounced::class,
],
];
```
```php title="app/Listeners/HandleEmailDelivered.php"
namespace App\Listeners;
use Lettermint\Laravel\Events\MessageDelivered;
class HandleEmailDelivered
{
public function handle(MessageDelivered $event): void
{
logger('Email delivered', [
'message_id' => $event->data->messageId,
'recipient' => $event->data->recipient,
]);
}
}
```
## Next Steps
Organize and filter emails with tags.
Track opens, clicks, and deliverability.
Receive real-time delivery notifications.
Send via SMTP instead of the API.
Find the complete source code, report issues, or contribute on GitHub.