Lettermint Laravel

https://github.com/lettermint/lettermint-laravel
Admin
Lettermint Laravel is an official Laravel driver that integrates Lettermint's email API for sending...
Tokens:45,953
Snippets:342
Trust Score:6.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Listening to all webhook events

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-events.md

Example of using `Event::listen` with the base class to receive every webhook event. The callback logs the event type and ID from the envelope.

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

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

### Usage example: configuring and resolving services

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Shows how to configure the package via config/services.php and resolve both the EmailEndpoint and ApiClient services from the container. Includes sending mail through the registered transport, direct low-level sending, and team API usage.

```php
use Lettermint\Client\ApiClient;
use Lettermint\Endpoints\EmailEndpoint;
use Illuminate\Support\Facades\Mail;

// config/services.php
// 'lettermint' => [
//     'token' => env('LETTERMINT_PROJECT_TOKEN', env('LETTERMINT_TOKEN')),
//     'api_token' => env('LETTERMINT_API_TOKEN'),
// ],

// Sending mail through the registered transport
Mail::to($user)->send(new WelcomeMail());

// Direct low-level sending via the container EmailEndpoint
$endpoint = app(EmailEndpoint::class); // or app('lettermint')
$response = $endpoint->from('hello@example.com')
    ->to('user@example.com')
    ->subject('Hello')
    ->html('<p>Hello</p>')
    ->send();

// Team API via the container ApiClient
$projects = app(ApiClient::class)->projects->list();
$team = app('lettermint.api')->team->retrieve();
```

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

### Install Lettermint Laravel package with Composer

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

Installs the Lettermint Laravel package via Composer. Requires PHP 8.2+ and Laravel 9+.

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

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

### Configure multiple Lettermint mailers with different settings

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

Configure multiple mailers sharing the Lettermint transport with different route_id and idempotency settings. This example defines a marketing mailer with idempotency disabled and a transactional mailer with a 3600-second idempotency window.

```php
'mailers' => [
    'lettermint_marketing' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_MARKETING_ROUTE_ID'),
        'idempotency' => false,
    ],
    'lettermint_transactional' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_TRANSACTIONAL_ROUTE_ID'),
        'idempotency' => true,
        'idempotency_window' => 3600,
    ],
],
```

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

### Error Handling with ApiTokenNotFoundException

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-facade.md

Error handling example showing how to catch ApiTokenNotFoundException when the project token is missing. The facade resolves the endpoint lazily, so the exception is thrown during the send call. Note that ApiTokenNotFoundException extends InvalidArgumentException.

```php
use Lettermint\Laravel\Facades\Lettermint;
use Lettermint\Laravel\Exceptions\ApiTokenNotFoundException;
use InvalidArgumentException;

try {
    Lettermint::from('hello@example.com')
        ->to('user@example.com')
        ->subject('Hello')
        ->html('<p>Hello</p>')
        ->send();
} catch (ApiTokenNotFoundException $exception) {
    Log::error('Lettermint is not configured: ' . $exception->getMessage());
} catch (InvalidArgumentException $exception) {
    // ApiTokenNotFoundException extends InvalidArgumentException
}
```

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

### Concrete example: MessageDelivered event class

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-events.md

Concrete implementation of the common pattern for the MessageDelivered event, using MessageDeliveredData as the data type. Located in src/Events/MessageDelivered.php lines 8–18.

```php
final class MessageDelivered extends LettermintWebhookEvent
{
    public function __construct(
        public readonly WebhookEnvelope $envelope,
        public readonly MessageDeliveredData $data,
    ) {}

    public function getEnvelope(): WebhookEnvelope
    {
        return $this->envelope;
    }
}
```

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

### WebhookSecretNotFoundException class

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

Thrown when a webhook request starts while config('lettermint.webhooks.secret') is empty. The trigger is VerifyWebhookSignature::handle() (src/Webhooks/VerifyWebhookSignature.php line 17), which checks if (empty($secret)) at the start of every webhook request. Because it runs before verification, this is an uncaught request-time failure (HTTP 500) when the secret is unset. The exception message is 'No Lettermint webhook secret was found. Please set the LETTERMINT_WEBHOOK_SECRET variable in your environment.'

```php
final class WebhookSecretNotFoundException extends InvalidArgumentException
{
    public static function create(): self
    {
        return new self(
            'No Lettermint webhook secret was found. Please set the LETTERMINT_WEBHOOK_SECRET variable in your environment.'
        );
    }
}
```

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

### Access envelope and typed data properties

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

Shows how to access common envelope properties (id, event, timestamp) and event-specific data properties, using MessageDelivered as an example. The envelope is common to all events, while data properties vary by event type.

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

// 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
```

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

### bootingPackage method

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Registers the routes/webhooks.php route file only when config('lettermint.webhooks.enabled', true) resolves truthy. Set LETTERMINT_WEBHOOK_ENABLED=false or webhooks.enabled => false to register the route manually.

```php
public function bootingPackage(): void
{
    // hasRoute cannot live in configurePackage: that hook runs before the
    // package config is merged, so webhooks.enabled would not be readable.
    if (config('lettermint.webhooks.enabled', true)) {
        $this->package->hasRoute('webhooks');
    }
}
```

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

### register method

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Runs parent registration and then binds both container services: the EmailEndpoint and the ApiClient.

```php
public function register(): void
{
    parent::register();

    $this->registerLettermintEmailEndpoint();
    $this->registerLettermintApiClient();
}
```

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

### boot method

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Registers the Symfony Mailer transport named 'lettermint' via Mail::extend. The closure receives the mailer's configuration array from config/mail.php and resolves app['lettermint'] (the EmailEndpoint binding) as the first constructor argument.

```php
public function boot(): void
{
    parent::boot();

    $app = $this->app;
    Mail::extend('lettermint', function (array $config = []) use ($app) {
        return new LettermintTransportFactory($app['lettermint'], $config);
    });
}
```

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

### Error handling in event listener for MessageDelivered

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-controller.md

Example of a listener that wraps its body in a try-catch to handle exceptions that bubble up from the event dispatch inside the controller. It logs the error with the envelope ID.

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

Event::listen(MessageDelivered::class, function (MessageDelivered $event) {
    try {
        HandleEmailDelivered::handle($event->data);
    } catch (Exception $exception) {
        Log::error('Listener failed for ' . $event->getEnvelope()->id, [
            'error' => $exception->getMessage(),
        ]);
    }
});
```

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

### Handle Lettermint transport exceptions

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-transport-factory.md

Catch transport-level failures as Symfony TransportException. The exception message starts with 'Sending email via Lettermint API failed: ' and the SDK error code is available via getCode().

```php
use Illuminate\Support\Facades\Mail;
use Symfony\Component\Mailer\Exception\TransportException;

try {
    Mail::to($user)->send(new WelcomeMail());
} catch (TransportException $exception) {
    Log::error('Send failed: ' . $exception->getMessage()); // "Sending email via Lettermint API failed: ..."
    Log::error('SDK code: ' . $exception->getCode());
}
```

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

### configurePackage method

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Configures the package name as 'lettermint' and declares config/lettermint.php as the package config file. The config file is published via `php artisan vendor:publish --tag="lettermint-config"`.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('lettermint')
        ->hasConfigFile();
}
```

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

### Run tests with Composer

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

Use this command to run the test suite for the package. It invokes the Composer test script, which typically runs PHPUnit or a similar testing framework.

```bash
composer test
```

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

### MessageDeliveredData::fromArray hydration pattern

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-data.md

Shows the common hydration pattern for webhook data classes. Reads snake_case payload keys, applies defaults with ?? for optional fields, and requires keys without fallbacks. Used as the example for MessageDeliveredData.

```php
public static function fromArray(array $data): self
{
    return new self(
        messageId: $data['message_id'],
        recipient: $data['recipient'],
        response: ServerResponse::fromArray($data['response']),
        metadata: $data['metadata'] ?? [],
        tag: $data['tag'] ?? null,
    );
}
```

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

### new Lettermint() instance proxy

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-facade.md

The facade can also be instantiated and used as an instance proxy, mirroring the endpoint object. This resolves the same container binding and allows the same fluent email sending methods.

```APIDOC
## new Lettermint() instance proxy

### Description
The facade can also be instantiated and used as an instance proxy, mirroring the endpoint object. This resolves the same container binding and allows the same fluent email sending methods.

### Method
Instance method chain (facade proxy)

### Endpoint
N/A (SDK method)

### Parameters
#### Method Chain Parameters
- **from** (string) - Required - The sender email address.
- **to** (string) - Required - The recipient email address.
- **subject** (string) - Required - The email subject.
- **text** (string) - Optional - The plain text content of the email.
- **send** () - Required - Sends the email.

### Request Example
```php
$facade = new Lettermint();
$result = $facade->from('hello@example.com')
    ->to('user@example.com')
    ->subject('Hello')
    ->text('Hello')
    ->send();
```

### Response
#### Success Response
Returns the result of the send operation (as defined by the EmailEndpoint).

#### Error Response
- **ApiTokenNotFoundException** - Thrown when no project token is configured.
- **InvalidArgumentException** - Base class for ApiTokenNotFoundException.

### Notes
- The facade resolves the endpoint lazily, so a missing project token surfaces as an ApiTokenNotFoundException.
```

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

### Instance-Style Facade Usage

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-facade.md

Instance-style access to the facade, creating a new Lettermint instance and calling methods on it. This resolves the same container binding as the static facade.

```php
use Lettermint\Laravel\Facades\Lettermint;

// Instance-style access — resolves the same container binding
$facade = new Lettermint();
$result = $facade->from('hello@example.com')
    ->to('user@example.com')
    ->subject('Hello')
    ->text('Hello')
    ->send();
```

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

### Combine tags and metadata using fluent methods

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

Use both tags and metadata together on a mailable instance with chained tag() and metadata() methods.

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

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

### VerifyWebhookSignature handle method implementation

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-signature-middleware.md

Full implementation of the handle method. It reads the webhook secret and tolerance from config, instantiates the SDK verifier, flattens headers, verifies the signature, and stores the payload on the request. On verification failure, it returns a 401 JSON response.

```php
public function handle(Request $request, Closure $next): Response
{
    $secret = config('lettermint.webhooks.secret');

    if (empty($secret)) {
        throw WebhookSecretNotFoundException::create();
    }

    $tolerance = (int) config('lettermint.webhooks.tolerance', 300);

    $webhook = new Webhook($secret, $tolerance);

    try {
        // Flatten headers array - Laravel returns array<string, list<string|null>>
        // but the SDK expects array<string, string>
        /** @var array<string, string> $headers */
        $headers = array_map(
            fn (array $value): string => $value[0] ?? '',
            $request->headers->all()
        );

        $payload = $webhook->verifyHeaders(
            $headers,
            $request->getContent()
        );

        $request->attributes->set('lettermint_webhook_payload', $payload);
    } catch (WebhookVerificationException $e) {
        return response()->json(['error' => 'Invalid signature'], 401);
    }

    return $next($request);
}
```

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

### Config Fallback for Project Token

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

Shows the default config fallback that still accepts the old LETTERMINT_TOKEN variable when LETTERMINT_PROJECT_TOKEN is not set.

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

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

### Publish Lettermint config file

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

Publishes the Lettermint configuration file to config/lettermint.php, where you can add your project and API tokens.

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

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

### Publish webhooks config in config/lettermint.php

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

Shows the webhooks configuration array with enabled, secret, prefix, and tolerance keys, reading from environment variables with defaults.

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

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

### Configure webhook secret and tolerance in .env

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-signature-middleware.md

Environment configuration for the webhook signing secret and optional tolerance. A missing secret fails fast during the request with a dedicated exception; configure it beforehand to avoid 500s.

```php
// .env
LETTERMINT_WEBHOOK_SECRET=your-webhook-signing-secret

// Optional
LETTERMINT_WEBHOOK_TOLERANCE=300
```

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

### Configure and send via Lettermint mailer

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-transport-factory.md

Configure the Lettermint transport in config/mail.php with route_id, idempotency, and idempotency_window, then send mail using the 'lettermint' mailer.

```php
'mailers' => [
    'lettermint' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_ROUTE_ID'),
        'idempotency' => true,
        'idempotency_window' => 3600,
    ],
],
```

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

Mail::mailer('lettermint')->to($user)->send(new WelcomeMail());
```

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

### provides(): array - List provided bindings

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Returns the parent's provided bindings plus ApiClient::class and EmailEndpoint::class. Used to declare which services the provider offers.

```php
public function provides(): array
{
    return [
        ...parent::provides(),
        ApiClient::class,
        EmailEndpoint::class,
    ];
}
```

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

### Lettermint Laravel config file (config/lettermint.php)

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

Default configuration file for the Lettermint Laravel package. Returns an array with keys for token, api_token, timeout, and webhooks settings. The token and api_token are optional but throw exceptions when missing at resolution. The timeout defaults to 15 seconds and webhooks are enabled by default with a prefix of 'lettermint' and a tolerance of 300 seconds.

```php
return [

    'token' => env('LETTERMINT_PROJECT_TOKEN', env('LETTERMINT_TOKEN')),

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

    'timeout' => (int) env('LETTERMINT_TIMEOUT', 15),

    'webhooks' => [

        'enabled' => env('LETTERMINT_WEBHOOK_ENABLED', true),

        'secret' => env('LETTERMINT_WEBHOOK_SECRET'),

        'prefix' => env('LETTERMINT_WEBHOOK_PREFIX', 'lettermint'),

        'tolerance' => env('LETTERMINT_WEBHOOK_TOLERANCE', 300),

    ],

];
```

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

### Handle webhook events with listeners and closures

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

Shows how to listen to MessageDelivered and MessageHardBounced events using the EventServiceProvider $listen array and closures, accessing event data.

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

// Or using closures
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,
    ]);
});

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

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

### Send Email with Lettermint Facade

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

Uses the Lettermint facade for low-level email sending. The facade resolves to the email endpoint.

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

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

### Add metadata using metadata() method

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

Recommended way to attach custom key-value pairs to an email using Laravel's native metadata() method. Chain multiple metadata() calls for multiple keys.

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

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

### Configure multiple mailers with different routes

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

Define multiple mailers using the Lettermint transport, each with its own route_id from environment variables. Then use them with Mail::mailer() to send different types of email.

```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'),
    ],
],
```

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

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

### registerLettermintApiClient(): void - Bind ApiClient with token resolution

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Binds the ApiClient to a factory that resolves the API token from config('lettermint.api_token') or config('services.lettermint.api_token'). Throws TeamApiTokenNotFoundException if neither is a string, and aliases the binding as 'lettermint.api'.

```php
protected function registerLettermintApiClient(): void
{
    $this->app->bind(ApiClient::class, static function (): ApiClient {
        $apiToken = config('lettermint.api_token') ?? config('services.lettermint.api_token');

        if (! is_string($apiToken)) {
            throw TeamApiTokenNotFoundException::create();
        }

        return LettermintSdk::api($apiToken, timeout: self::requestTimeout());
    });
    $this->app->alias(ApiClient::class, 'lettermint.api');
}
```

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

### VerifyWebhookSignature::handle

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-signature-middleware.md

Documentation for the VerifyWebhookSignature middleware's handle method, which verifies webhook signatures and stores the payload.

```APIDOC
## VerifyWebhookSignature::handle(Request $request, Closure $next): Response

### Description
Verifies the HMAC-style webhook request signature using the shared webhook secret and a timestamp-tolerance window. On success, stores the verified payload on the request attributes for downstream handling; on failure, returns a 401 JSON response.

### Method
handle

### Signature
```php
public function handle(Request $request, Closure $next): Response
```

### Parameters
- **$request** (Illuminate\Http\Request) - Required - The incoming webhook request.
- **$next** (Closure) - Required - The next middleware/controller in the chain.

### Returns
- **Response** - Either the chain's response (signature valid) or a 401 JSON response `{"error": "Invalid signature"}` (verification failed).

### Behavior
1. Reads `config('lettermint.webhooks.secret')`; if empty, throws `WebhookSecretNotFoundException`.
2. Reads `$tolerance = (int) config('lettermint.webhooks.tolerance', 300)` (seconds).
3. Instantiates the SDK verifier: `new Lettermint\Webhook($secret, $tolerance)`.
4. Flattens Laravel's header list-of-lists into a `array<string, string>` map (first value per header name, `''` when absent) as the SDK expects.
5. Calls `$webhook->verifyHeaders($headers, $request->getContent())`; on success stores the decoded payload into `$request->attributes->set('lettermint_webhook_payload', $payload)`.
6. On `Lettermint\Exceptions\WebhookVerificationException` (SDK), short-circuits with HTTP 401 `{"error": "Invalid signature"}`.
7. Otherwise continues the chain via `$next($request)`.

### Throws
- `Lettermint\Laravel\Webhooks\Exceptions\WebhookSecretNotFoundException` - when `config('lettermint.webhooks.secret')` is empty.
- Any non-`WebhookVerificationException` error propagates uncaught (unexpected SDK/IO failures).

### Source
`src/Webhooks/VerifyWebhookSignature.php` lines 14–45.
```

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

### MessageOpenedData class

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-data.md

Data class for the 'message.opened' webhook event. Constructor requires messageId, recipient, and openedAt; subject, tag, deviceType, clientType, clientName, userAgent, and bot are nullable; metadata defaults to [] and firstOpen to false. fromArray maps message_id and recipient as required, opened_at as required (converted to DateTimeImmutable), subject defaults to null, metadata to [], tag to null, first_open to false, device_type/client_type/client_name/user_agent to null, and bot to BotDetectionData::fromArray only when the bot key is an array, else null.

```php
final readonly class MessageOpenedData
{
    public function __construct(
        public string $messageId,
        public ?string $subject,
        public array $metadata,
        public ?string $tag,
        public string $recipient,
        public DateTimeImmutable $openedAt,
        public bool $firstOpen,
        public ?string $deviceType,
        public ?string $clientType,
        public ?string $clientName,
        public ?string $userAgent,
        public ?BotDetectionData $bot,
    ) {}
}
```

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

### Configure webhook prefix and tolerance in .env

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

Optionally sets the route prefix and timestamp tolerance for webhook verification via environment variables.

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

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

### __toString method implementation

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-transport-factory.md

Returns the transport name 'lettermint' as a string.

```php
public function __toString(): string
{
    return 'lettermint';
}
```

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

### Webhook route registration with domain constraint

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-controller.md

Optional route registration constrained to a specific domain using the domain method and a group closure.

```php
Route::domain('mail.example.com')->group(function () {
    Route::post('/webhook', WebhookController::class)
        ->name('lettermint.webhook')
        ->middleware(VerifyWebhookSignature::class);
});
```

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

### Constructor signature

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-transport-factory.md

Constructor for LettermintTransportFactory. Requires an EmailEndpoint instance and accepts an optional configuration array. The parent constructor is called.

```php
public function __construct(
    protected EmailEndpoint $emailEndpoint,
    protected array $config = []
) {
    parent::__construct();
}
```

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

### Listen to all webhook events with LettermintWebhookEvent

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

Registers a listener for all Lettermint webhook events using the base event class. Logs the event type and ID from the envelope. Use this to handle any webhook event generically.

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

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

### Configure idempotency in config/mail.php

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

Shows how to enable or disable automatic idempotency and set the deduplication window per mailer. The 'lettermint' mailer enables it with a 24-hour window, while 'lettermint_marketing' disables automatic idempotency but still respects user headers.

```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
    ],
],
```

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

### Handle unknown wire string with FromStringException

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-event-type.md

Handle unknown wire strings when converting to a WebhookEventType. The from() method throws FromStringException for unrecognized values, which is caught here to log an error.

```php
try {
    $type = WebhookEventType::from($wireValue); // e.g. from a DB replay
} catch (FromStringException $exception) {
    Log::error('Unknown webhook event: ' . $wireValue);
}
```

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

### Lettermint::from()->to()->subject()->html()->send()

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-facade.md

Sends an email using the Lettermint facade. The facade forwards static calls to the EmailEndpoint, allowing a fluent interface to compose and send an email.

```APIDOC
## Lettermint::from()->to()->subject()->html()->send()

### Description
Sends an email using the Lettermint facade. The facade forwards static calls to the EmailEndpoint, allowing a fluent interface to compose and send an email.

### Method
Static method chain (facade proxy)

### Endpoint
N/A (SDK method)

### Parameters
#### Method Chain Parameters
- **from** (string) - Required - The sender email address.
- **to** (string) - Required - The recipient email address.
- **subject** (string) - Required - The email subject.
- **html** (string) - Optional - The HTML content of the email.
- **text** (string) - Optional - The plain text content of the email.
- **send** () - Required - Sends the email.

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

### Response
#### Success Response
Returns the result of the send operation (as defined by the EmailEndpoint).

#### Error Response
- **ApiTokenNotFoundException** - Thrown when no project token is configured.
- **InvalidArgumentException** - Base class for ApiTokenNotFoundException.

### Notes
- The facade resolves the endpoint lazily, so a missing project token surfaces as an ApiTokenNotFoundException.
- The facade targets sending email only; the Team API client is not behind this facade.
```

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

### Add API Token to services.php Config

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

Adds the API token to the Lettermint configuration when using config/services.php.

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

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

### Add metadata using envelope method

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

Attach metadata by defining the envelope() method in your Mailable class. Use the metadata array with 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,
        ],
    );
}
```

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

### TeamApiTokenNotFoundException class

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

Thrown when resolving the container ApiClient (app(ApiClient::class) / app('lettermint.api')) while no API token is configured. The trigger is LettermintServiceProvider::registerLettermintApiClient() (src/LettermintServiceProvider.php line 73), which evaluates config('lettermint.api_token') ?? config('services.lettermint.api_token') and throws when the result is not a string. The exception message is 'No Lettermint API token was found. Please set the LETTERMINT_API_TOKEN variable in your environment.'

```php
final class TeamApiTokenNotFoundException extends InvalidArgumentException
{
    public static function create(): self
    {
        return new self(
            'No Lettermint API token was found. Please set the LETTERMINT_API_TOKEN variable in your environment.'
        );
    }
}
```

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

### MessageClickedData class

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-data.md

Data class for the 'message.clicked' webhook event. Constructor requires messageId, recipient, clickedAt, destinationUrl, and linkIndex; subject, tag, anchorText, deviceType, clientType, clientName, userAgent, and bot are nullable; metadata defaults to [] and firstClick to false. fromArray maps message_id, recipient, destination_url, and link_index (int-cast) as required, clicked_at as required (converted to DateTimeImmutable), subject defaults to null, metadata to [], tag to null, anchor_text to null, first_click to false, device_type/client_type/client_name/user_agent to null, and bot to BotDetectionData::fromArray only when the bot key is an array, else null.

```php
final readonly class MessageClickedData
{
    public function __construct(
        public string $messageId,
        public ?string $subject,
        public array $metadata,
        public ?string $tag,
        public string $recipient,
        public DateTimeImmutable $clickedAt,
        public string $destinationUrl,
        public int $linkIndex,
        public ?string $anchorText,
        public bool $firstClick,
        public ?string $deviceType,
        public ?string $clientType,
        public ?string $clientName,
        public ?string $userAgent,
        public ?BotDetectionData $bot,
    ) {}
}
```

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

### registerLettermintEmailEndpoint method

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Binds Lettermint\Endpoints\EmailEndpoint to a factory that creates LettermintSdk::email($projectToken, timeout: ...). Token resolution order is config('lettermint.token') then config('services.lettermint.token'); throws Lettermint\Laravel\Exceptions\ApiTokenNotFoundException when neither is a string. Aliases the binding as 'lettermint'.

```php
protected function registerLettermintEmailEndpoint(): void
{
    $this->app->bind(EmailEndpoint::class, static function (): EmailEndpoint {
        // A user can configure the project token in the config file or in the services config file.
        $projectToken = config('lettermint.token') ?? config('services.lettermint.token');

        if (! is_string($projectToken)) {
            throw ApiTokenNotFoundException::create();
        }

        return LettermintSdk::email($projectToken, timeout: self::requestTimeout());
    });
    $this->app->alias(EmailEndpoint::class, 'lettermint');
}
```

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

### Set Project Token Environment Variable

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

Sets the project token used for sending email through Laravel mail. This is the preferred variable over the old LETTERMINT_TOKEN.

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

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

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

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

In your config/mail.php, set the default option to 'lettermint' with the transport key. This enables the Lettermint mail transport.

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

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

### Common event class shape (with X = DataClass substituted)

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-events.md

Shows the verbatim pattern for every event class E with data type D. The constructor promotes the envelope and data properties, and getEnvelope() returns the envelope.

```php
final class E extends LettermintWebhookEvent
{
    public function __construct(
        public readonly WebhookEnvelope $envelope,
        public readonly D $data,
    ) {}

    public function getEnvelope(): WebhookEnvelope
    {
        return $this->envelope;
    }
}
```

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

### Custom webhook route registration with domain constraint

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-signature-middleware.md

Custom registration of the webhook route with a domain constraint and extra middlewares. Includes the necessary imports for Route, VerifyWebhookSignature, and WebhookController.

```php
use Illuminate\Support\Facades\Route;
use Lettermint\Laravel\Webhooks\VerifyWebhookSignature;
use Lettermint\Laravel\Webhooks\WebhookController;

Route::domain('events.example.com')->group(function () {
    Route::post(
        config('lettermint.webhooks.prefix', 'lettermint').'/webhook',
        WebhookController::class
    )->name('lettermint.webhook')
        ->middleware(VerifyWebhookSignature::class);
});
```

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

### Error handling: catching missing token exceptions

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Shows how to catch the specific exceptions thrown when the container resolves services without the required token configuration. ApiTokenNotFoundException is thrown for 'lettermint' and TeamApiTokenNotFoundException for 'lettermint.api'; both extend InvalidArgumentException.

```php
use Lettermint\Laravel\Exceptions\ApiTokenNotFoundException;
use Lettermint\Laravel\Exceptions\TeamApiTokenNotFoundException;
use InvalidArgumentException;

try {
    $endpoint = app('lettermint');
} catch (ApiTokenNotFoundException $exception) {
    Log::error($exception->getMessage()); // "...set the LETTERMINT_PROJECT_TOKEN..."
}

try {
    $client = app('lettermint.api');
} catch (TeamApiTokenNotFoundException $exception) {
    Log::error($exception->getMessage()); // "...set the LETTERMINT_API_TOKEN..."
}

// Both extend InvalidArgumentException, so a common handler works too:
catch (InvalidArgumentException $exception) { /* ... */ }
```

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

### Combine tags and metadata in envelope method

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

Define both tags and metadata in the envelope() method of a Mailable class for combined usage.

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

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

### Register Lettermint mailer transport in config/mail.php

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

Register the Lettermint transport in config/mail.php by adding a mailer block with transport set to 'lettermint'. The entire block array is passed as the constructor $config to LettermintTransportFactory. The transport reads route_id, idempotency, and idempotency_window keys.

```php
'mailers' => [
    'lettermint' => [
        'transport' => 'lettermint',
        'route_id' => env('LETTERMINT_ROUTE_ID'),
        'idempotency' => true,
        'idempotency_window' => 86400,
    ],
],
```

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

### VerifyWebhookSignature class and handle method signature

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-signature-middleware.md

Shows the class signature and the public handle method signature for the VerifyWebhookSignature middleware. The handle method is the entry point that Laravel calls for middleware.

```php
class VerifyWebhookSignature
{
    public function handle(Request $request, Closure $next): Response
}
```

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

### WebhookController __invoke method implementation

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-controller.md

The __invoke method reads the verified payload from the request attributes, converts the event string to a WebhookEventType enum, fires the corresponding event, and returns a JSON response with status 'ok'.

```php
public function __invoke(Request $request): JsonResponse
{
    /** @var array<string, mixed> $payload */
    $payload = $request->attributes->get('lettermint_webhook_payload');

    $eventType = WebhookEventType::from($payload['event']);

    event($eventType->toEvent($payload));

    return response()->json(['status' => 'ok']);
}
```

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

### Use WebhookEventType helper methods

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

Demonstrates helper methods on the WebhookEventType enum to check for bounce and delivery issue events. isBounce() returns true for hard/soft bounces, while isDeliveryIssue() returns true for bounces, failed, and suppressed events.

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

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

### Send email with custom Idempotency-Key header

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-transport-factory.md

Send an email with a custom Idempotency-Key header. This key overrides any configured idempotency key.

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

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

### WebhookEventType Enum

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/webhook-event-type.md

Documentation for the WebhookEventType enum, including its cases and methods.

```APIDOC
## Enum: WebhookEventType

### Description
String-backed Blade enum that enumerates every Lettermint webhook event type, classifies events, and acts as the factory that turns a raw webhook payload into a typed `LettermintWebhookEvent` instance.

### Namespace
`Lettermint\Laravel\Webhooks`

### Import Path
`use Lettermint\Laravel\Webhooks\WebhookEventType;`

### Source File
`src/Webhooks/WebhookEventType.php`

### Enum Declaration
```php
enum WebhookEventType: string
{
    case MessageCreated = 'message.created';
    case MessageSent = 'message.sent';
    case MessageDelivered = 'message.delivered';
    case MessageHardBounced = 'message.hard_bounced';
    case MessageSoftBounced = 'message.soft_bounced';
    case MessageSpamComplaint = 'message.spam_complaint';
    case MessageFailed = 'message.failed';
    case MessageSuppressed = 'message.suppressed';
    case MessagePolicyRejected = 'message.policy_rejected';
    case MessageUnsubscribed = 'message.unsubscribed';
    case MessageOpened = 'message.opened';
    case MessageClicked = 'message.clicked';
    case MessageInbound = 'message.inbound';
    case WebhookTest = 'webhook.test';

    public function isBounce(): bool

    public function isDeliveryIssue(): bool

    public function toEvent(array $rawPayload): LettermintWebhookEvent
}
```

### Enum Cases
| Case | Value | Produced event class |
|---|---|---|
| `MessageCreated` | `message.created` | `Lettermint\Laravel\Events\MessageCreated` |
| `MessageSent` | `message.sent` | `Lettermint\Laravel\Events\MessageSent` |
| `MessageDelivered` | `message.delivered` | `Lettermint\Laravel\Events\MessageDelivered` |
| `MessageHardBounced` | `message.hard_bounced` | `Lettermint\Laravel\Events\MessageHardBounced` |
| `MessageSoftBounced` | `message.soft_bounced` | `Lettermint\Laravel\Events\MessageSoftBounced` |
| `MessageSpamComplaint` | `message.spam_complaint` | `Lettermint\Laravel\Events\MessageSpamComplaint` |
| `MessageFailed` | `message.failed` | `Lettermint\Laravel\Events\MessageFailed` |
| `MessageSuppressed` | `message.suppressed` | `Lettermint\Laravel\Events\MessageSuppressed` |
| `MessagePolicyRejected` | `message.policy_rejected` | `Lettermint\Laravel\Events\MessagePolicyRejected` |
| `MessageUnsubscribed` | `message.unsubscribed` | `Lettermint\Laravel\Events\MessageUnsubscribed` |
| `MessageOpened` | `message.opened` | `Lettermint\Laravel\Events\MessageOpened` |
| `MessageClicked` | `message.clicked` | `Lettermint\Laravel\Events\MessageClicked` |
| `MessageInbound` | `message.inbound` | `Lettermint\Laravel\Events\MessageInbound` |
| `WebhookTest` | `webhook.test` | `Lettermint\Laravel\Events\WebhookTest` |

### Methods

#### isBounce(): bool

##### Description
Returns whether the event type represents a bounce (hard or soft bounce).

##### Returns
- **bool** - `true` if the event is a bounce, `false` otherwise.

#### isDeliveryIssue(): bool

##### Description
Returns whether the event type represents a delivery issue (hard bounce, soft bounce, spam complaint, failed, suppressed, policy rejected, or unsubscribed).

##### Returns
- **bool** - `true` if the event is a delivery issue, `false` otherwise.

#### toEvent(array $rawPayload): LettermintWebhookEvent

##### Description
Creates a typed `LettermintWebhookEvent` instance from the raw webhook payload based on the event type.

##### Parameters
- **$rawPayload** (array) - Required - The raw webhook payload.

##### Returns
- **LettermintWebhookEvent** - The corresponding typed event instance.
```

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

### LettermintServiceProvider class signature

Source: https://github.com/lettermint/lettermint-laravel/blob/main/_autodocs/api-reference/lettermint-service-provider.md

Shows the public and protected method signatures of the LettermintServiceProvider class, which extends Spatie\LaravelPackageTools\PackageServiceProvider. Use this as an overview of the provider's structure before reading the detailed method implementations.

```php
class LettermintServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void

    public function bootingPackage(): void

    public function boot(): void

    public function register(): void

    protected function registerLettermintEmailEndpoint(): void

    protected function registerLettermintApiClient(): void

    private static function requestTimeout(): int

    public function provides(): array
}
```

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

### Update Published Config with api_token

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

Adds the new api_token key to the published config/lettermint.php file. Includes webhook settings with defaults for prefix and tolerance.

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

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

### ApiTokenNotFoundException class

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

Thrown when resolving the container EmailEndpoint (app(EmailEndpoint::class) / app('lettermint')) or facade while no project token is configured. The trigger is LettermintServiceProvider::registerLettermintEmailEndpoint() (src/LettermintServiceProvider.php line 58), which evaluates config('lettermint.token') ?? config('services.lettermint.token') and throws when the result is not a string. The exception message is 'No Lettermint project token was found. Please set the LETTERMINT_PROJECT_TOKEN variable in your environment.'

```php
final class ApiTokenNotFoundException extends InvalidArgumentException
{
    public static function create(): self
    {
        return new self(
            'No Lettermint project token was found. Please set the LETTERMINT_PROJECT_TOKEN variable in your environment.'
        );
    }
}
```
Tokens:
Raw