Mailflow Laravel Package

Product Decisions This Supports

• Build vs. buy for outbound delivery. The v2.5.0 transactional outbox (retry with 30 s / 2 min / 10 min / hourly backoff up to 72 h, ack-by-key, expired resolution via GET /api/send/{key}) is the classic "don't build your own retry table" argument. If a roadmap item says "guarantee invoice/legal notifications are delivered," this package is the cheaper path than a bespoke queue + reconciliation service.
• Reliability commitments (SLA / contractual). Ack keys, outbox statuses (pending/sending/acked/expired/failed/superseded), stuck-row recovery at 10 min, and heartbeat every 5 min give you the observability needed to actually promise a delivery guarantee and to report on it.
• Duplicate-avoidance during provider incidents. The emergency-send path is the strongest product story here: reportExternalSend() marks the outbox row superseded (and throws OutboxRowInFlight if the message is already in flight), so a manual fallback send does not produce a second email to the customer. This directly supports a documented incident runbook and a "no double-billing emails" quality bar.
• Notification-as-code / release governance. F-009 atomic provisioning (provisionPackage, validatePackage, smartmailto:provision --validate) plus the per-project variable catalog means message templates and workflows can live in Git, be reviewed in PRs, validated in CI, and applied all-or-nothing. That's a product-velocity decision: who can change customer-facing copy, and how it gets reviewed.
• Contact data ownership and sync direction. F-011 pull (POST {prefix}/smartmailto/pull, signed cursor, PullResolver) plus last-write-wins on updatedAt forces an explicit product decision: which system is the source of truth per attribute. Good support for "app is the system of record, marketing tool mirrors it."
• Invoice / attachment-based products. F-008 attachments (fromPath/fromData/fromUpload, plus fromDisk with a fresh 24 h signed URL per retry, fromUrl with sha256) unblocks e-invoicing and statement delivery; the 1 MB inline cap with outbox enabled is a product constraint to design around (force disk/URL for big PDFs).
• Privacy / compliance workflows. smartmailto:outbox:prune retention defaults (acked 7 days, closed 30 days), per-contact ARCO deletion, identify(..., consent: true) re-consent, and failure events deliberately carrying no personal data give legal/DPO a reviewable story.
• Operational readiness decisions. The package now publishes its first migration (smartmailto_outbox, smartmailto_outbox_alert_state). That is a real platform decision: does a vendor SDK own tables in the app database, or do we dedicate outbox.connection? It also implies a supervised worker (smartmailto:outbox:work) as a new production dependency.
• Alerting/on-call design. Grouped, escalating alerts (email alerts.mail_to + Teams adaptive card at 15 min, 1 h, 4 h, 12 h, 24 h, 48 h, 72 h digest, "recovered"; 422s immediately, grouped per template in 15 min windows) replaces "someone notices emails stopped." Supports a support-tier decision: is failed-notification triage L1 or engineering?
• Test strategy. SmartmailtoFake covering reportExternalSend(), assertLinked(), assertExternalSendReported(), fakePull() with assertPullContract(), and provisioning asserts determines whether we can keep CI hermetic — a gating criterion in any build-vs-buy scorecard.
• Vendor lock-in posture. Not on Packagist, VCS-only install, Spanish-only docs, and 2.2.0–2.4.0 never separately tagged. This argues for wrapping the SDK behind an internal Notifier interface so switching costs stay bounded — a decision worth making now, not later.

When to Consider This Package

Consider it when:

• You're on a Laravel app that can absorb illuminate/database, illuminate/encryption, illuminate/filesystem, illuminate/mail and symfony/yaml (verify the supported Laravel/PHP matrix against your runtime before committing).
• Message loss is a genuine business risk: invoices, legal notices, account-security or transactional statements — i.e., you need retries, expiry semantics, and an auditable record.
• You can upgrade the Smartmailto server to at least F-010, and ideally F-008/F-009/F-011. Feature-flagged defaults (SMARTMAILTO_OUTBOX_ENABLED=false, SMARTMAILTO_PULL_ENABLED=false and no routes registered) mean you can adopt incrementally, but also that half-enabled deployments silently deliver none of the value.
• You can run and supervise a long-lived worker and put the heartbeat on a dashboard; you can also accept new tables in your DB or provision a dedicated connection.
• You need contact sync from the app out to the messaging platform and want a signed, throttled, cursor-based pull rather than a homegrown webhook.
• Your team can work from Spanish documentation and is comfortable pinning a VCS repository (tags/commits) instead of relying on Packagist semver.

Look elsewhere when:

• You only need fire-and-forget transactional email and already get acceptable reliability from Laravel's mail/queue stack — the outbox, migrations, and worker are net new operational surface for little gain.
• You need provider portability (SES/SendGrid/Postmark abstraction) or multi-vendor failover. This is a dedicated SDK to one service.
• You cannot run background workers, cannot add tables, or cannot rotate APP_KEY safely — outbox payloads are encrypted with APP_KEY, so key rotation makes in-flight rows unreadable.
• The server cannot be upgraded; provisioning commands will 404 and the outbox features go inert.
• You require Packagist-grade release traceability (three versions shipping untagged in one release is a flag) or mature English documentation for a broad team.
• Your compliance regime requires vendor certifications or data-residency guarantees that a small single-maintainer package can't evidence.
• You need channels beyond email + Teams alerts.

How to Pitch It (Stakeholders)

For executives (one paragraph): v2.5.0 upgrades this SDK from "a helper that sends email" into a delivery-reliability layer. It adds a transactional outbox — every message is written in the same database transaction as the business event, retried on a defined backoff for up to 72 hours, and only closed when the platform acknowledges it with a key — plus a documented emergency-send path that prevents customers receiving the same invoice twice during an outage. It also brings automated escalation alerts (email and Teams), attachment support (including disk/URL attachments regenerated per retry), and infrastructure-as-code for templates and workflows with CI validation. Cost: two new tables, one supervised worker, and a dependency on server-side feature flags. Net: we can credibly commit to "critical notifications are not lost and not duplicated," and we get an audit trail to prove it.

For engineering: the outbox is off by default and fully backward compatible, but enabling it changes contracts — send() requires sendBefore, a track without occurredAt stores commit time, identify transmits updated_at, and the package owns a migration you must publish with --tag=smartmailto-migrations. Plan a dedicated outbox.connection, add smartmailto:outbox:work to the supervisor, wire SmartmailtoOutboxFailed (needsEmergencySend()) into on-call, and schedule smartmailto:outbox:status, :retry, :prune. Wrap the SDK behind an internal interface; note the README no longer recommends sending directly off health(), and that install is VCS-only with "agavesoft/smartmailto": "^2.5".

For product/ops: templates and workflows become reviewable artifacts (smartmailto:provision --validate in CI, atomic apply, all-or-nothing with per-item error reporting), copy changes stop being a console-only activity, and retention/consent behaviour (prune --contact=, re-consent) is explicit enough to take to legal. Recommended sequencing: adopt with the outbox disabled, enable it for exactly one high-value flow (e.g., invoice delivery), measure ack rate and duplicate rate for a release cycle, then expand.