Postmark Php Laravel Package

Technical Evaluation

Architecture fit

• This is a framework-agnostic SDK, not a Laravel package. It ships no service provider, no config publish, no facade, and no Laravel-native testing fakes. Every ergonomic decision — container bindings, config shape, exception mapping, retry policy — becomes ours to build and own.
• Laravel's Mail facade already covers transactional sending to Postmark through the built-in transport (Symfony Mailer's Postmark API transport). A direct SDK dependency is therefore redundant for the primary send path and should not be adopted as the mail driver.
• Genuine value sits in the surface area Laravel's transport does not expose: template management, batch/bulk sending, message streams, inbound message parsing and webhook payload hydration, suppressions/bounces, sender signatures, domain and server management, and message-events/search APIs.
• Recommended posture: Mail facade for outbound transactional mail; SDK behind our own interfaces for inbound webhooks, template and stream administration, and deliverability telemetry. Anything else expands our blast radius for no delivery benefit.

Integration feasibility

• composer require plus a thin service provider is a day of work at most. MIT license is clean; no legal review beyond standard attribution.
• The real integration cost is not the install, it's the seams: mapping SDK exceptions into Laravel's handler and notification failure paths, and making the client testable without hitting the live API.
• The SDK is a single-provider client with no abstraction layer of its own, so it does not help us hedge. If provider portability is a stated goal, this package provides zero leverage toward it — a competing SDK is a rewrite, not a config flip.

Technical risk

• HTTP stack collision (highest technical risk). The SDK historically bundles its own HTTP client (Guzzle) rather than accepting PSR-18 injection. Two Guzzle majors in one tree is a classic transitive-dependency landmine. Confirm PSR-18/PSR-17 support before committing; if absent, we accept a second HTTP client with separate timeout, retry, and proxy semantics.
• Vendor concentration. Postmark-specific payloads (streams, templates, inbound hash/signature verification, event shapes) leak into our domain if we don't wrap them. The wrapper is what converts vendor lock-in into a swap-in-a-week decision.
• Maturity signal. 176 stars reads low, but this is a narrow official SDK — star count is a poor proxy here. Weight the release cadence (last release 2025-07-11) and Packagist install volume instead.
• Bus factor. Maintained by Postmark/Wildbit with limited external contribution. If the SDK stalls, we pin and maintain a fork; the wrapper keeps that fork small.
• Opportunity score of 1.52 argues against over-investing: this is commodity plumbing, not a differentiator. Budget it as a supporting integration, not a roadmap item.

Key questions

1. Does the client support PSR-18 injection, or does it hard-depend on a specific Guzzle major?
2. Does it expose retry, timeout, and 429 Retry-After handling, or must we implement backoff around it?
3. What is its PHP version floor and does it match our Laravel version matrix?
4. Are webhook signatures (inbound and delivery) verified by the SDK or by us?
5. Does it ship a recorded-response test fixture set we can reuse for offline tests?
6. What is Postmark's published rate limit and batch cap for our account tier?

Integration Approach

Stack fit

• Clean fit for Laravel 10/11/12 on PHP 8.1+, but only as a supplementary client. Do not displace the framework mail transport for routine transactional mail — we would lose queue integration, Markdown mailables, mail fakes, and Mail::assertSent coverage.
• Adopt the SDK for three confined capabilities: inbound webhook parsing, stream/template administration, and bounce/suppression/event queries feeding internal deliverability reporting.

Migration path

1. Abstract first. Define PostmarkClientInterface (or narrower capability interfaces: InboundParser, TemplateAdmin, DeliveryInsights) and bind the SDK behind it in a dedicated app/Services/Postmark namespace.
2. Shadow, don't cut over. Install and exercise the SDK against a non-production Postmark server. Zero production send-path changes in this phase.
3. Move inbound webhooks first — lowest blast radius, highest immediate value (bounce/complaint suppression loops currently manual or absent).
4. Then admin/telemetry (streams, templates, event queries) reading only.
5. Only then consider any write operations on templates/streams, and never the transactional send path.

Compatibility

• Pin exact versions in composer.json and require a green CI run before bumping. Add a composer why-not check in the dependency-upgrade runbook.
• Verify Guzzle/PSR resolution against our existing tree (Horizon, AWS SDK, and any Laravel HTTP-client consumers) before rollout.
• Test against Laravel's Http::fake or a Guzzle mock handler; do not let SDK calls reach the network in CI.

Sequencing

Wrapper interfaces → config + secrets → inbound webhook handler (with signature verification and idempotency keys) → deliverability reporting job → template/stream administration (read) → optional write operations. Gate each step behind a Postmark server token scoped to a non-production server until the final step.

Operational Impact

Maintenance

• Low, bounded: ~2–5 engineering days per year for version bumps and Laravel-upgrade compatibility checks — provided the wrapper stays thin and the send path stays on the framework transport. Cost rises sharply if the SDK becomes load-bearing for sending.
• We own the wrapper indefinitely. Treat it as internal code with an owner, not as an installed dependency.

Support

• Commercial support flows through the Postmark account relationship, not the repository. GitHub issues are best-effort community triage. Escalation path is the Postmark support desk, which is a contract question, not a code question.
• Document the fork-and-pin contingency: MIT license means we can vendor and patch, and a thin wrapper keeps that patch to a handful of files.

Scaling

• Throughput is gated by Postmark's account-tier rate limits and batch caps, not by the SDK. Confirm both against our projected send volume and our queue worker concurrency before any volume assumption enters a plan.
• The SDK is synchronous and stateless — it will block a queue worker for the duration of the HTTP call. Run it on dedicated queue workers or wrap calls in short timeouts so a slow Postmark response cannot starve other jobs.

Failure modes

• Auth (401/403): misconfigured or rotated server token — must fail loudly and page, not silently drop mail.
• Validation (422): malformed payloads or unapproved sender signatures; surface per-message errors rather than a batch-level failure.
• Rate limit (429): needs explicit backoff with Retry-After honored; unbounded retries will amplify an incident.
• Transient 5xx / timeouts: retry with idempotency where the API allows; otherwise accept duplicate-send risk consciously.
• Webhook duplicates and replays: mandatory idempotency on message ID; without it, suppression counts and deliverability dashboards drift.
• Signature verification gaps: unverified inbound webhooks are an injection vector into our suppression and bounce state.
• Silent degradation: if the wrapper swallows SDK exceptions, we lose bounce signals and deliverability decays invisibly over weeks. Alert on exception rate, not just on job failure.

Ramp-up

• A mid-level PHP developer familiar with Postmark can ship the wrapper and inbound handler in 2–3 days; total first-value effort is about one sprint-week including tests and secret management.
• The steep part is not the SDK — it is deliverability operations: suppression policy, bounce classification, stream strategy, and webhook idempotency. Budget SME time there, and treat 1–2 days of Postmark documentation and deliverability-guide review as mandatory onboarding for whoever owns the integration.
• Add a short ADR recording the decision to use the SDK narrowly rather than as the mail driver, so a future maintainer doesn't "simplify" by routing sends through it.