Laravel Postmark Laravel Package

Product Decisions This Supports

• Build vs. buy for deliverability feedback loops: This package covers the plumbing between Postmark's webhook payloads and application-level domain events. Building this in-house is a few days of work plus ongoing maintenance as Postmark evolves its payload schema; adopting it turns that into a composer require plus a route registration. The decision is now mostly about whether you want webhook handling to be a maintained dependency or owned code.
• Feature: bounce and complaint handling (deliverability hygiene): EmailBounced and EmailComplained events give you the hooks to suppress bad addresses, flag accounts, and protect sender reputation. InactiveRecipients specifically targets Postmark's 406 "inactive recipient" rejections and extracts the offending addresses — this is the raw material for an automatic suppression list, which is a compliance and deliverability requirement rather than a nice-to-have.
• Feature: engagement tracking (EmailOpened, EmailClicked): Enables product-level decisions like "did this onboarding sequence land," per-user engagement scoring, or triggering in-app nudges from email activity. Useful, but treat open tracking as directional only (Apple Mail Privacy Protection and image blocking distort it) — don't let a roadmap decision hinge on open rates alone.
• Feature: subscription lifecycle (EmailSubscriptionChanged): Lets you reconcile Postmark's subscription state with your own preferences model, so unsubscribes propagate to your product rather than living only in the ESP. This is the event that reduces "we emailed someone who opted out" incidents.
• Roadmap sequencing / scope control: Because each webhook becomes a typed event dispatched through your queue, the PM can scope this as "one integration sprint" rather than an open-ended project. The event taxonomy is fixed and enumerable (RecordType maps record type → event), so the backlog item can be written concretely: which events do we consume, what do we store, what do we act on.
• Operational decision — queue isolation: The ProcessPostmarkWebhook job exposes configurable connection and queue. That's a deliberate product-level lever: webhook traffic spikes (a large send, a provider incident) shouldn't starve user-facing jobs. Worth deciding up front rather than discovering during an incident.
• Security posture as a decision input: VerifyPostmarkWebhook enforces HTTP Basic Auth on the endpoint, and the route macro wires it in. This lets you accept webhook traffic on a public URL without a bespoke auth story, which shortens security review and reduces the chance of shipping an unauthenticated endpoint under deadline pressure.

When to Consider This Package

Adopt when:

• Postmark is your transactional or marketing email provider and you handle more than fire-and-forget sends — i.e. you need to react to bounces, complaints, or unsubscribes.
• You're on PHP 8.2–8.4 and Laravel 11–13, matching the supported matrix. Older Laravel or PHP 8.1 and below is a hard no.
• Your team prefers Postmark-specific integration code over a generic, provider-agnostic email abstraction layer. If you're multi-provider or actively evaluating switching ESPs, a generic layer is the better bet.
• You run (or plan to run) queue workers. The job-based design assumes asynchronous processing; synchronous-only setups get less value and should confirm the job runs inline acceptably.
• You want typed event objects with payload, metadata, client, and location accessors rather than hand-parsing raw JSON — the ergonomics here are the main ongoing developer-experience win.

Look elsewhere or build in-house when:

• You need outbound sending (templates, sends, message streams). This package is inbound webhook handling only — it does not replace the Postmark SDK.
• You need durable audit storage of every raw webhook. The package converts payloads to events; persistence, replay, and idempotency guarantees are your responsibility, not the package's.
• You are on a Laravel version outside 11–13, or need LTS longevity beyond what the current support matrix promises.
• You require a vendor with a support contract, SLA, or security disclosure process. This is a 1.0.0 first release with no established track record — treat maturity as unproven until you've run it in production.
• Your compliance model requires data residency or vendor review of every dependency; a small third-party package adds review overhead disproportionate to its scope.

Adoption caveats to plan for: version 1.0.0 means the pre-1.0 churn risk is behind it, but the project has no demonstrated release history. Pin the version, wrap the events in your own handlers rather than coupling business logic directly to package classes, and verify the middleware actually rejects unsigned/incorrectly-authenticated requests in a staging test before trusting it. Also decide explicitly what happens when the queue backs up or a job fails — webhooks are not retried indefinitely by Postmark, so a poison job can silently lose a bounce.

How to Pitch It (Stakeholders)

To executives: This is a small, focused library that connects Postmark's email delivery notifications to our application. It lets us automatically handle bounces, spam complaints, and unsubscribes instead of relying on manual processes or in-house glue code. The business value is sender reputation and list hygiene — bad addresses and complaints damage deliverability for everyone, which directly affects whether revenue-generating email reaches the inbox. Cost is near-zero (a dependency, not a service), and the work is a contained integration rather than a project.

To engineering: First stable release of a Postmark webhook package for Laravel 11–13 / PHP 8.2–8.4. It registers an authenticated webhook route via Route::postmarkWebhooks(), verifies HTTP Basic Auth in VerifyPostmarkWebhook, and dispatches a queued ProcessPostmarkWebhook job with configurable connection and queue so webhook traffic can be isolated from user-facing work. Payloads arrive as typed events (EmailBounced, EmailDelivered, EmailOpened, EmailClicked, EmailComplained, EmailSubscriptionChanged) with typed accessors for payload, metadata, client, and location; a RecordType enum maps record types to events. InactiveRecipients parses Postmark's 406 inactive-recipient rejections and extracts the addresses, which is the hook for automated suppression.

Known gaps to state plainly: no outbound sending, no built-in persistence or replay of raw webhooks, no idempotency guarantees, and no support contract. Treat 1.0.0 as early — pin the version, keep business logic in our own listeners, and add a staging test that confirms the middleware rejects bad credentials before this goes anywhere near production.