Prontuno Laravel Laravel Package

Product Decisions This Supports

• Build vs. buy on transactional email infrastructure. The package collapses a large slice of "email platform" work—sending, suppression management, domain setup, webhook ingestion, SMTP credentials—into a Laravel-native dependency. The PM decision becomes whether email deliverability and reputation management are core differentiators (build/own) or undifferentiated plumbing (buy/adopt). For most product teams this is a clear buy, and this package is the buy-side integration.
• Shipping email-dependent features without growing platform scope. Onboarding sequences, password resets, receipts, digests, comment/mention notifications, and multi-tenant outbound mail all route through Mail:: as normal, so feature teams don't relearn an SDK per feature. That keeps roadmap estimates for email-touching features close to estimates for non-email features.
• Multi-tenant and multi-brand architecture choices. withSendingKey() (per-domain mailer) and usingApiKey() (single-key client, returns a new client) make per-tenant sending a first-class pattern rather than an afterthought. This informs decisions about whether one deployment serves many brands or many deployments serve one brand each.
• Inbound event-driven roadmap. Signed webhooks with timestamp tolerance and typed WebhookEvent constants unblock delivery events (bounces, complaints, opens/clicks if exposed) as triggers for lifecycle messaging, suppression sync, and customer-facing delivery status—without polling.
• Data hygiene and compliance posture. Suppressions API plus per-endpoint webhook secrets support unsubscribe/bounce suppression flows and segregated secret handling for sensitive event types (the prontuno.webhook:billing named-secret pattern suggests separating billing events from general traffic).
• Reliability SLOs and support-cost planning. Idempotency keyed on Message-ID, retries on 408/429/5xx with Retry-After, and no double-send on retry directly reduce duplicate-charge and duplicate-email incidents. Retryable flags and suggested actions on ApiException shape how much error-handling code product teams must own versus inherit.
• Operational/debuggability decisions. X-Prontuno-Email-ID on sent messages, request IDs on errors, and fresh signed download links for sent attachments make "where did this email go?" a support-deflectable question rather than an engineering escalation.
• Vendor lock-in and exit-cost modeling. Because it's built on Laravel's HTTP client (Http::fake() in tests) and mirrors Laravel's own mail/exception primitives, the switching cost is mostly the transport swap plus webhook and suppression re-plumbing—worth stating explicitly in any make-vs-buy memo.
• Scope boundary for a framework-agnostic client. If the roadmap includes non-Laravel services (Go workers, Node marketing site, Python data jobs), the parallel prontuno/prontuno-php client means the email decision shouldn't be scoped as "Laravel only."

When to Consider This Package

Consider it when most of the following hold:

• Laravel 12 or 13 on PHP 8.3+, or a credible near-term upgrade path. Older Laravel/PHP versions are explicitly out of scope—check this before it reaches a roadmap commitment.
• Email is a supporting capability, not the product. Transactional and notification mail that must work reliably but isn't where engineering differentiation lives.
• You want standard Laravel mail semantics. Any Mailable, notification, or Mail::raw() should flow through unchanged via MAIL_MAILER=prontuno; teams shouldn't need a bespoke sending API in feature code.
• Multi-domain or multi-tenant sending is real or anticipated. Per-domain mailers via key, plus withSendingKey()/usingApiKey(), are the deciding features if you serve multiple brands or tenants.
• You need webhook-driven delivery events, and you want signature verification, timestamp tolerance, and route middleware handled rather than hand-rolled.
• Suppression and sender-reputation workflows matter. Bounce/complaint suppression via API rather than manual list scrubbing.
• You value testability as a gate. Http::fake() compatibility means QA and CI can cover sending paths without hitting a live provider—worth weighting if email regressions have burned you.
• You want key separation by blast radius. Distinct sending and management keys, with clear ConfigurationException failures before any request leaves the process.

Look elsewhere or wait when:

• You're not on Laravel 12/13 + PHP 8.3+, or you can't commit to that baseline.
• You need a mature, battle-tested integration. This is v0.1.0—the first public release. Expect API surface movement before 1.0; treat it as an early-adopter bet, not a stability guarantee. Pin versions and budget for upgrade work.
• You require provider-side features not enumerated here—dedicated IPs, inbound email parsing, advanced template/design tooling, or deliverability consulting. Confirm these exist on the Prontuno platform, not just this SDK.
• You need framework-agnostic or non-PHP clients as the primary path—use prontuno/prontuno-php or another SDK instead.
• Your compliance regime demands vendor certifications, DPAs, or data residency guarantees you haven't yet verified with the vendor. Nothing here speaks to those; that's a separate diligence track.
• You need guaranteed exactly-once semantics everywhere. Idempotency is keyed on Message-ID and email sends retry only when you pass an idempotency key—that's a behavioral contract your code must honor.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can stop treating transactional email as an in-house platform problem. prontuno/prontuno-laravel is the official, MIT-licensed Laravel integration for the Prontuno API: it plugs into Laravel's native mail system, so sending email, managing suppression lists, rotating webhook secrets, and handling delivery events become configuration rather than engineering projects. It reduces duplicate-send and duplicate-charge risk through idempotency-keyed retries, cuts support load with per-message IDs and actionable error metadata, and supports multi-brand and multi-tenant sending without extra architecture. The trade-off: it's a v0.1.0 first release requiring PHP 8.3+ and Laravel 12/13, so it's an early-adopter commitment with some pre-1.0 churn risk—appropriate for teams willing to pin versions and absorb minor upgrades, and worth a time-boxed pilot before it becomes load-bearing.

For engineering leads: Adoption is deliberately low-friction. Composer install; service provider and Prontuno facade auto-discover; publish config with php artisan vendor:publish --tag=prontuno-config; set MAIL_MAILER=prontuno and you're sending through the standard Mail facade with from/to/cc/bcc/reply-to, text and HTML bodies, custom headers, and attachments including inline ones. Everything is .env-configurable (keys, base URL, timeouts, retries, webhook secrets and tolerance, PRONTUNO_APP_INFO for User-Agent attribution). Sending and management keys are separated, and calling a method whose key isn't configured throws ConfigurationException before any network request—fail-fast rather than silent misconfiguration. For multi-tenancy, withSendingKey() and usingApiKey() return new clients (immutable, no shared mutable state), and per-domain mailers take their own key. Retry behavior is opinionated and sensible: GET/DELETE retry on 408/429/5xx and connection failures, Retry-After honored up to 60s, timeouts per attempt, and a retried DELETE succeeds if the first attempt already removed the resource. Webhooks are verified HMAC over the raw request body with a 300s default tolerance via prontuno.webhook middleware or WebhookVerifier::fromRequest() in your own controller, returning a typed WebhookEvent. Pagination gives you list() for one page or lazy() as a LazyCollection across all pages with a page limit and repeated-cursor protection. Errors are typed—ApiException (status, code, request ID, retryable, suggested action, retry-after, field-level errors per batch item, raw body), ConnectionException extending Laravel's own, plus ConfigurationException and PaginationException. Tests can use Http::fake() throughout. Two things to enforce in code review: pass explicit idempotency keys on email sends if you want retries, and never verify webhook signatures against a re-encoded payload.

For product and support: This directly improves the customer-facing story around "I didn't get the email." Sent messages carry an X-Prontuno-Email-ID header, errors carry request IDs and suggested actions, and sent attachments are retrievable via fresh signed links—so support can diagnose without engineering. Suppression APIs mean unsubscribes and bounces get honored systematically rather than through manual list maintenance, which is a compliance and sender-reputation win. The caveats to communicate upward: it's a first release, the version pin matters, and a pilot with a clear success metric (send-to-delivery time, duplicate-send rate, support ticket volume on email issues) is a better commitment than an immediate org-wide mandate.