Laravel Talario Laravel Package

Getting Started

1. Install (VCS until Packagist)

v1.0.0 is not on Packagist yet, so composer require alone will fail. Add the repository first:

{
  "repositories": [
    { "type": "vcs", "url": "https://github.com/muehleis/laravel-talario" }
  ]
}

composer require muehleis/laravel-talario:^1.0

Then commit composer.json and composer.lock — CI runners and teammates cannot resolve the package otherwise. Check PHP constraints: 8.2+ on Laravel 12, 8.3+ on Laravel 13.

2. Where to look first

• README.md — the authority on config keys, credential env var names, and the documented API limitations (the release notes explicitly defer to it; it is not optional reading).
• config/mail.php — you add the mailer entry yourself; the package registers the transport, not your mailer.
• CHANGELOG.md — for the limitation list between minor releases.

3. Configure the mailer

Package discovery registers the talario transport, so no manual provider wiring is needed. Add a mailer block in config/mail.php:

'mailers' => [
    'talario' => [
        'transport' => 'talario',
        // credential / endpoint keys per README
    ],
],

and point the default at it:

MAIL_MAILER=talario

Prefer a dedicated mailer name (talario) plus MAIL_MAILER=log in .env.example and local dev, so nobody accidentally sends live mail from a laptop or burns send quota in tests.

4. First use case — one real send before you build anything

Mail::raw('Talario smoke test', fn ($m) => $m->to('[email protected]')->subject('v1.0.0'));

Then repeat with a Mailable that has an HTML view, one file attachment, a Bcc, and an embed(). The release notes confirm all four were live-verified, so they are the right first probes — do them in one go and inspect the received message, not just the absence of an exception.

Implementation Patterns

Normal Mailable flow. Nothing special is required: build Mailables, render Blade views, use attach(), attachFromStorage(), cc(), bcc(), replyTo(). The driver consumes the already-built Symfony Email, so your Mailable code stays portable to SMTP/SES if you need to swap.

Per-mailer targeting instead of global default. Keep MAIL_MAILER=talario for production but address the mailer explicitly wherever it matters:

Mail::mailer('talario')->to($user)->send(new Receipt($order));

This makes it cheap to run two providers side by side (e.g. Talario for transactional, SMTP for internal alerts) and to canary a single code path.

Embedded images. Use embed() for files on disk and embedData() for generated/binary content. Attach the returned $cid to the src yourself:

public function build()
{
    $cid = $this->embed(public_path('img/logo.png'));

    return $this->view('mail.receipt', ['logoSrc' => 'cid:'.$cid]);
}

Prefer embedData() when the image is generated (QR codes, chart snapshots) — it avoids temp files and is the pattern that maps most directly to what the release notes verified.

Queued mail. A ShouldQueue Mailable is still the right default, but see the retry gotcha below: the transport does not retry HTTP, while the queue will retry the job. Set public $tries = 1; (or a very tight $backoff plus an idempotency key on your side) for any Mailable that must not double-send.

Notifications. The mail channel works unchanged — notifications go through the same mailer, so no extra integration code. Verify one notification path if you use Bcc for audit copies, since that is the part most likely to differ per provider.

Testing. Mail::fake() asserts your Mailable was queued/sent, never that the transport worked — it bypasses the driver entirely. So split your suite:

• Unit/feature tests: Mail::fake() + assertSent, assertHasAttachment, assertSeeInHtml.
• One or two tagged integration tests hitting Talario with a real recipient, run manually or in a nightly job, gated behind an env flag and skipped when credentials are absent.

Multi-tenant / multi-brand. Define several mailers (talario, talario_billing) sharing the driver but with different credentials or from-addresses; this keeps per-brand configuration in config/mail.php rather than in application code.

Gotchas and Tips

No automatic HTTP retries — this is a design decision, not a gap. After an ambiguous timeout the message may already have been accepted; the package deliberately refuses to guess. Consequences:

• Laravel's queue worker will still retry a failed job and will resend. Cap it ($tries = 1) or make sends idempotent at the application layer.
• Do not wrap Mail::send() in your own retry() helper.
• Surface hard failures to the user or an outbox table rather than silently swallowing them.

HTTPS only, redirects disabled. A http:// endpoint, an internal host that 301s to HTTPS, or a URL with a trailing slash that redirects will fail rather than follow. If you proxy outbound traffic, make sure the proxy answers on the exact configured URL and does not respond with a redirect.

Bounded timeouts. There is a ceiling on connect/response time. If you send large attachments or embed several high-resolution images, expect occasional timeouts — encode images at a sane size, and push heavy sends to the queue so a slow send doesn't stall a web request.

Sanitized transport exceptions. Exceptions are wrapped and scrubbed, so laravel.log may show a short message without the provider's raw response body. For hard-to-reproduce failures, temporarily log $e->getPrevious() and the mailable's recipient/subject around the send; don't expect the HTTP payload to be in the exception message.

Embedded images break on CID mismatch. If the image renders as a broken attachment, the cid: in your HTML doesn't match the returned Content-ID. Dump the embed() return value, confirm you render cid:{$cid} verbatim (no extra quotes, no rewriting in a CSS background-image inlined differently), and remember some clients won't render background-image from CID at all.

Discovery can be off. If the talario transport is reported as unsupported, you likely have dont-discover entries or a cached manifest. Run php artisan package:discover and php artisan config:clear — the second one bites hardest after editing config/mail.php.

VCS install is temporary but sticky. composer.lock will pin a specific commit hash, not a version tag, until Packagist registration. When the package lands on Packagist, remove the repositories entry and re-require with a normal constraint, or you'll keep resolving the git source forever.

Extension points. Because the driver plugs into the mail manager, you can decorate it — register your own transport that delegates to Talario and adds logging, metrics, or an outbox write — without forking. Keep the decorator thin: anything that re-invokes the transport on failure reintroduces the duplicate-send risk the package is avoiding.

Version pinning. Pin ^1.0 and read CHANGELOG.md before each bump; a 1.x that adds an opt-in retry flag would silently change your duplicate-send posture.