Lettermint Laravel Laravel Package

Getting Started

1. Install the package and publish its config:

   composer require lettermint/lettermint-laravel
   php artisan vendor:publish --tag="lettermint-config"
   

2. Add your credentials to .env:

   LETT ERMINT_API_KEY=your-api-key
   LETT ERMINT_WEBHOOK_SECRET=your-webhook-signing-secret
   

3. Point Laravel's mailer at the package. In config/mail.php:

   'mailers' => [
       'lettermint' => [
           'transport' => 'lettermint',
       ],
   ],
   

   and set MAIL_MAILER=lettermint.

Where to look first: read config/lettermint.php (or the published config/lettermint.php) to see the API key, base URL, and webhook settings, then check the package README for the webhook route registration and event names. The service provider wires the transport and registers the webhook endpoint, so most day-to-day work happens in your existing app/Mail mailables and a webhook controller/listener.

First use case: send a standard Mailable through the new transport — nothing else changes:

Mail::to($user)->send(new WelcomeEmail($user));

Once that works, wire up the webhook endpoint so delivery/open/bounce events from Lettermint flow into your app.

Implementation Patterns

• Transactional mail via the Mail facade. Keep using Mailables and Notifications exactly as before; the package only swaps the transport. This is the lowest-risk way to adopt it — no changes to your mail classes, just the mailer config.
• Lower-level API calls via the facade. For things that don't map to a Mailable (managing templates, domains, suppressions, etc.), use the Lettermint facade. Treat it as the escape hatch when the mail transport abstraction is too narrow.
• Webhook ingestion. Register the package's webhook route (or point Lettermint at your own controller) and handle the inbound events. Verify the signature with the configured webhook secret before trusting the payload. Persist raw payloads first, then process asynchronously in a queued job so a slow handler doesn't cause retries/timeouts on the provider side.
• Event-driven side effects. The package dispatches events for outbound messages (and, as of 3.1.0, exposes the message headers on those outbound events). Listen for these to correlate provider-side message IDs with your own records, log headers for deliverability debugging (e.g. Message-ID, custom X- headers), or forward to observability tooling.
• Multiple mailers. Because it's a normal Laravel mailer, you can keep smtp/ses configured alongside lettermint and select per-mail via Mail::mailer('lettermint')->to(...) — useful for staged rollouts or routing different notification classes through different providers.
• Testing. Mail::fake() continues to work; assert on the mailable as usual. For webhook tests, post signed payloads to the endpoint and assert your listeners/jobs ran; use the package's signing helper or replicate the HMAC if exposed.
• Queuing. Send mailables with ShouldQueue (or Mail::queue) as normal — the package's HTTP calls to the API happen inside the queued job, so retries/backoff are governed by your queue worker config.

Gotchas and Tips

• Header exposure is new in 3.1.0. If you're upgrading from 3.0.x, the outbound message events now carry the message headers. This is additive, but if you have listeners that serialize the event payload (e.g. into a log or a json column), verify the added field doesn't break strict schemas or snapshot tests. Don't assume the header key is present on every event — check the event's accessor/property rather than reading an array key blindly.
• Webhook security is on you. Always validate the signing secret and reject unsigned requests. Exclude the webhook URI from CSRF (bootstrap/app.php / VerifyCsrfToken $except) — a 419 from Laravel looks like an outage to the provider and triggers retries.
• Idempotency. Webhook providers retry. Store the provider's event/message ID and make handlers idempotent, otherwise you'll double-send or double-record events.
• Config cache. After changing config/mail.php or config/lettermint.php, run php artisan config:clear (and remember config:cache in production). A stale config cache is the most common "why is it still using SMTP?" cause.
• Driver name mismatch. The transport value in config/mail.php must match what the package registers. If you get "Transport [lettermint] is not defined," the service provider isn't loaded (check package discovery / composer dump-autoload) or you're on a cached config.
• Missing API key fails late. A blank LETT ERMINT_API_KEY often surfaces as a 401 at send time rather than at boot. Add a config/boot check or an assertion in your deploy health check.
• Debugging. Since mail now leaves via HTTP, Log the provider response and message ID on failure; enable the package's debug logging if available. For webhook issues, log the raw body before verification so you can distinguish "bad signature" from "malformed payload."
• Extension points. Prefer listening to the package's events over subclassing the transport. If you need custom behavior (extra headers, retry policy), set headers on the Mailable ($mailable->withSymfonyMessage(...) / headers()) — and with 3.1.0 you can confirm what actually went out by inspecting the headers on the outbound event.