### Install Lettermint Laravel Driver

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Install the package using Composer. Ensure you have PHP 8.2+ and Laravel 9+.

```bash
composer require lettermint/lettermint-laravel
```

--------------------------------

### Update Composer Dependencies

Source: https://github.com/lettermint/lettermint-laravel/blob/main/UPGRADE.md

Run this command to update the Lettermint Laravel package to version 2.0 or higher. This also ensures the correct version of the PHP SDK is installed.

```bash
composer require lettermint/lettermint-laravel:^2.0
```

--------------------------------

### Run Tests

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Execute the test suite for the Laravel package using Composer.

```bash
composer test
```

--------------------------------

### Configure Multiple Mailers with Different Routes

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Set up multiple mailers in config/mail.php, each using the Lettermint transport but with distinct route IDs for marketing and transactional emails.

```php
// config/mail.php
'mailers' => [
    'lettermint_marketing' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_MARKETING_ROUTE_ID'),
    ],
    'lettermint_transactional' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_TRANSACTIONAL_ROUTE_ID'),
    ],
],
```

--------------------------------

### Configure Optional Webhook Settings

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Optionally configure the route prefix and timestamp tolerance in your .env file.

```env
LETTERMINT_WEBHOOK_PREFIX=lettermint
LETTERMINT_WEBHOOK_TOLERANCE=300
```

--------------------------------

### Using the Lettermint Facade

Source: https://github.com/lettermint/lettermint-laravel/blob/main/UPGRADE.md

The Lettermint facade is used for low-level email sending and resolves to the email endpoint. It utilizes the project token.

```php
Lettermint::from('hello@example.com')
    ->to('user@example.com')
    ->subject('Hello')
    ->html('<p>Hello</p>')
    ->send();
```

--------------------------------

### Publish Lettermint Configuration

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Publish the configuration file to your Laravel project. This creates config/lettermint.php for your API tokens.

```bash
php artisan vendor:publish --tag="lettermint-config"
```

--------------------------------

### Add Lettermint Service to config/services.php

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Register the Lettermint service with its token configuration in your config/services.php file.

```php
    'lettermint' => [
        'token' => env('LETTERMINT_PROJECT_TOKEN', env('LETTERMINT_TOKEN')),
        'api_token' => env('LETTERMINT_API_TOKEN'),
    ],
```

--------------------------------

### Listen to All Webhook Events

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Use the base LettermintWebhookEvent class to listen for all incoming webhook events.

```php
use Lettermint\Laravel\Events\LettermintWebhookEvent;

Event::listen(LettermintWebhookEvent::class, function (LettermintWebhookEvent $event) {
    Log::info('Webhook received', [
        'type' => $event->getEnvelope()->event->value,
        'id' => $event->getEnvelope()->id,
    ]);
});
```

--------------------------------

### Update services.php Config with API Token

Source: https://github.com/lettermint/lettermint-laravel/blob/main/UPGRADE.md

If you configure Lettermint in config/services.php, ensure you add the 'api_token' key alongside the existing token configuration.

```php
'lettermint' => [
    'token' => env('LETTERMINT_PROJECT_TOKEN', env('LETTERMINT_TOKEN')),
    'api_token' => env('LETTERMINT_API_TOKEN'),
],
```

--------------------------------

### Add Tag using Custom Header (X-LM-Tag)

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

For backward compatibility, you can use the `X-LM-Tag` custom header. The driver automatically converts this to the `TagHeader` envelope method.

```php
use Illuminate\Mail\Mailables\Headers;

class WelcomeEmail extends Mailable
{
    public function headers(): Headers
    {
        return new Headers(
            text: [
                'X-LM-Tag' => 'onboarding',
            ],
        );
    }
}
```

--------------------------------

### Accessing Team API with SDK

Source: https://github.com/lettermint/lettermint-laravel/blob/main/UPGRADE.md

Use the PHP SDK API client from Laravel's container to access team resources. This client uses the LETTERMINT_API_TOKEN.

```php
use Lettermint\Client\ApiClient;

$projects = app(ApiClient::class)->projects->list();
$team = app('lettermint.api')->team->retrieve();
```

--------------------------------

### Add Metadata using Mail::send()

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Attach custom key-value pairs to emails using the `metadata()` method when sending via `Mail::send()`. This is recommended for enhanced tracking.

```php
Mail::send((new OrderConfirmation($order))
    ->metadata('order_id', $order->id)
    ->metadata('customer_id', $order->customer_id)
);
```

--------------------------------

### Configure Webhook Signing Secret

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Add your webhook signing secret to the .env file for signature verification.

```env
LETTERMINT_WEBHOOK_SECRET=your-webhook-signing-secret
```

--------------------------------

### Add Lettermint Transport to config/mail.php

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Configure the default mailer to use the 'lettermint' transport in your config/mail.php file.

```php
        'lettermint' => [
            'transport' => 'lettermint',
        ],
```

--------------------------------

### Combine Tags and Metadata using Mail::send()

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

You can chain `tag()` and `metadata()` methods when sending emails via `Mail::send()` to include both categorization and custom data.

```php
Mail::send((new OrderShipped($order))
    ->tag('transactional')
    ->metadata('order_id', $order->id)
    ->metadata('tracking_number', $order->tracking_number)
);
```

--------------------------------

### Update Environment Variable for Project Token

Source: https://github.com/lettermint/lettermint-laravel/blob/main/UPGRADE.md

Set the LETTERMINT_PROJECT_TOKEN in your .env file for sending emails. The old LETTERMINT_TOKEN is still supported as a fallback.

```env
LETTERMINT_PROJECT_TOKEN=your-lettermint-project-token
```

--------------------------------

### Publish and Modify Webhook Configuration

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Publish the config file to modify webhook settings directly in config/lettermint.php.

```php
// config/lettermint.php
'webhooks' => [
    'secret' => env('LETTERMINT_WEBHOOK_SECRET'),
    'prefix' => env('LETTERMINT_WEBHOOK_PREFIX', 'lettermint'),
    'tolerance' => env('LETTERMINT_WEBHOOK_TOLERANCE', 300),
]
```

--------------------------------

### Update Published Config with API Token

Source: https://github.com/lettermint/lettermint-laravel/blob/main/UPGRADE.md

If you have published the config file, add the 'api_token' key to your config/lettermint.php. This configuration uses environment variables for tokens and webhook settings.

```php
return [
    'token' => env('LETTERMINT_PROJECT_TOKEN', env('LETTERMINT_TOKEN')),

    'api_token' => env('LETTERMINT_API_TOKEN'),

    'webhooks' => [
        'secret' => env('LETTERMINT_WEBHOOK_SECRET'),
        'prefix' => env('LETTERMINT_WEBHOOK_PREFIX', 'lettermint'),
        'tolerance' => env('LETTERMINT_WEBHOOK_TOLERANCE', 300),
    ],
];
```

--------------------------------

### Accessing Event Envelope Properties

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Demonstrates how to access common envelope properties like ID, event type, and timestamp for any webhook event.

```php
// Envelope (common to all events)
$event->envelope->id;        // Webhook event ID (string)
$event->envelope->event;     // WebhookEventType enum
$event->envelope->timestamp; // DateTimeImmutable
```

--------------------------------

### Configure Mailer Idempotency Settings

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Configure idempotency behavior per mailer in your `config/mail.php`. You can enable/disable automatic content-based idempotency and set the time window for deduplication.

```php
'mailers' => [
    'lettermint' => [
        'transport' => 'lettermint',
        'idempotency' => true, // Enable automatic content-based idempotency
        'idempotency_window' => 86400, // Window in seconds (default: 24 hours)
    ],
    'lettermint_marketing' => [
        'transport' => 'lettermint',
        'route_id' => 'marketing',
        'idempotency' => false, // Disable automatic idempotency
    ],
],
```

--------------------------------

### Combine Tags and Metadata using Mailable Envelope

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Both tags and metadata can be defined within the `envelope()` method of a Mailable class, providing a consolidated way to set email attributes.

```php
public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Your order has shipped!',
        tags: ['transactional', 'shipping'],
        metadata: [
            'order_id' => $this->order->id,
            'tracking_number' => $this->order->tracking_number,
            'carrier' => $this->order->carrier,
        ],
    );
}
```

--------------------------------

### Handle MessageDelivered Event Using Closures

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Use closures to listen for and handle the MessageDelivered event, logging relevant details.

```php
Event::listen(MessageDelivered::class, function (MessageDelivered $event) {
    Log::info('Email delivered', [
        'message_id' => $event->data->messageId,
        'recipient' => $event->data->recipient,
        'status_code' => $event->data->response->statusCode,
    ]);
});
```

--------------------------------

### Update Environment Variable for API Token

Source: https://github.com/lettermint/lettermint-laravel/blob/main/UPGRADE.md

Add the LETTERMINT_API_TOKEN to your .env file for accessing the Team API.

```env
LETTERMINT_API_TOKEN=your-lettermint-api-token
```

--------------------------------

### Add Tag using Mail::send()

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Use the `tag()` method directly on the Mailable instance when sending via `Mail::send()` to categorize emails.

```php
use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;

Mail::send((new WelcomeEmail($user))
    ->tag('onboarding')
);
```

--------------------------------

### Specify Route ID in config/mail.php

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Configure a specific Lettermint route ID for a mailer by adding the 'route_id' option in config/mail.php.

```php
'lettermint' => [
    'transport' => 'lettermint',
    'route_id' => env('LETTERMINT_ROUTE_ID'),
],
```

--------------------------------

### Handle Specific Webhook Events in EventServiceProvider

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Listen to specific Lettermint webhook events by defining them in your Laravel EventServiceProvider.

```php
use Lettermint\Laravel\Events\MessageDelivered;
use Lettermint\Laravel\Events\MessageHardBounced;
use Lettermint\Laravel\Events\MessageSpamComplaint;

// In EventServiceProvider
protected $listen = [
    MessageDelivered::class => [
        HandleEmailDelivered::class,
    ],
    MessageHardBounced::class => [
        HandleEmailBounced::class,
    ],
];
```

--------------------------------

### Set Custom Idempotency Key Header

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Override configuration by setting a custom idempotency key in the email headers using `addTextHeader('Idempotency-Key', 'your-key-here')`. This header is always respected.

```php
Mail::send('emails.welcome', $data, function ($message) {
    $message->to('user@example.com')
        ->subject('Welcome!')
        ->getHeaders()->addTextHeader('Idempotency-Key', 'welcome-user-123');
});
```

--------------------------------

### Check for Delivery Issues

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Use the `isDeliveryIssue()` helper method to identify events related to bounces, failures, or suppressions.

```php
$event->envelope->event->isDeliveryIssue(); // true for bounces, failed, suppressed
```

--------------------------------

### Add Metadata using Mailable Envelope

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Define metadata as an associative array within the `envelope()` method of your Mailable class. This allows for multiple key-value pairs.

```php
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,
        ],
    );
}
```

--------------------------------

### Handle MessageHardBounced Event

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Implement logic to handle permanent email bounces, such as disabling the recipient.

```php
Event::listen(MessageHardBounced::class, function (MessageHardBounced $event) {
    // Handle permanent bounce - consider disabling the recipient
    $recipient = $event->data->recipient;
    $reason = $event->data->response->content;
});
```

--------------------------------

### Check for Bounce Events

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Use the `isBounce()` helper method to determine if an event is a hard or soft bounce.

```php
$event->envelope->event->isBounce();        // true for hard/soft bounces
```

--------------------------------

### Accessing MessageDelivered Event Data Properties

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Shows how to access specific data properties for the MessageDelivered event, including response details and metadata.

```php
// Data (typed per event)
// For MessageDelivered:
$event->data->messageId;              // string
$event->data->recipient;              // string
$event->data->response->statusCode;   // int
$event->data->response->content;      // string|null
$event->data->metadata;               // array
$event->data->tag;                    // string|null
```

--------------------------------

### Send Email Using Specific Mailers

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Utilize different mailers configured with specific Lettermint route IDs to send marketing or transactional emails in your Laravel application.

```php
Mail::mailer('lettermint_marketing')->to($user)->send(new MarketingEmail());
Mail::mailer('lettermint_transactional')->to($user)->send(new TransactionalEmail());
```

--------------------------------

### Add Tag using Mailable Envelope

Source: https://github.com/lettermint/lettermint-laravel/blob/main/README.md

Define tags within the `envelope()` method of your Mailable class for a cleaner approach. Only one tag is supported directly in the envelope.

```php
use Illuminate\Mail\Mailables\Envelope;

class WelcomeEmail extends Mailable
{
    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Welcome to our platform!',
            tags: ['onboarding'], // Only one tag is allowed
        );
    }
}
```

--------------------------------

### Sending Email with Laravel Mail

Source: https://github.com/lettermint/lettermint-laravel/blob/main/UPGRADE.md

Laravel mail usage remains the same. The mail transport automatically uses the LETTERMINT_PROJECT_TOKEN for sending.

```php
Mail::to($user)->send(new WelcomeMail());
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.