Laravel Scoped Mail Config Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin decorator over Laravel's Mail facade: a HasMailConfig contract on a scope model (Tenant/Team/User) plus a facade that resolves mail configuration at send time. Surface area is small, so vendor lock-in is low — if it's abandoned we can vendor or reimplement the few classes involved.
• Genuine fit for multi-tenant SaaS that needs per-tenant sending identity (SMTP/SES/Postmark credentials, from address, local domain). It targets spatie/laravel-multitenancy explicitly by name; compatibility with stancl/tenancy or custom tenancy layers is unverified.
• It owns configuration selection only — not delivery, queueing, retries, webhooks, or bounce/complaint handling. Any deliverability and reputation work remains ours.
• The README is internally inconsistent: it imports Lacodix\LaravelScopedMailConfig\Concerns\HasMailConfig but declares implements HasMailConfig. Whether the contract is an interface, a trait, or both must be confirmed in source before anyone estimates work against it.

Integration feasibility

• Mechanically simple: composer require, one line in AppServiceProvider (ScopedMail::resolveScopeUsing(...)), one getMailConfig($name): array method. A half-day spike is realistic.
• The real cost is call-site migration. Every tenant-scoped send must move from Mail:: to ScopedMail::. That touches notifications, queued mailables, password resets, invites, and any third-party package (Fortify, Breeze, Cashier, Nova) that sends through the default facade — those keep using the global config silently and invisibly.
• Laravel 10/11/12 are supported across the release history; PHP requirements follow the framework. No exotic dependencies or extensions.

Technical risk

• Queue workers are the top risk. Default scope resolution is the authenticated user. That context does not exist inside a queued mailable or a worker process, so queued mail either falls back to the global config or, if the scope is stale, sends under the wrong tenant identity. Unless the tenant is serialized onto the mailable and rehydrated in handle(), this package is a demo, not a production system.
• Long-lived processes. Runtime mail-config mutation on a shared container can bleed across requests under Octane, Swoole, or queue workers. Verify the implementation resolves per send rather than mutating global mail.* keys.
• Secret storage. Credentials live on the tenant model — meaning per-tenant SMTP passwords in the database, in backups, in dumps, and potentially in logs and serialized payloads. This requires encrypted casts, key rotation, and log exclusion. It is a security review item, not a footnote.
• Maintenance posture. 1 star, 0 dependents, a single maintainer, no visible security policy or community channel. Treat it as unsupported code. The mitigant is that MIT plus a tiny surface makes forking cheap.
• Test coverage gap. ScopedMail::fake() only covers the new facade. Existing Mail::fake() assertions will not catch an unscoped send, so scope regressions can ship green.

Key questions

1. Do we need per-tenant credentials, or only per-tenant from-address/branding? The latter is dramatically cheaper and safer — one verified sending domain with per-tenant aliases.
2. What is scope resolution in queue, CLI, and scheduler contexts, and what is the fallback? Fail-closed (refuse to send) or fail-open (global config)?
3. Are we prepared to own the ops surface the package doesn't cover — bounce/complaint webhooks, per-tenant DKIM/SPF onboarding, reputation isolation, deliverability alerting?
4. Build vs. buy: is a 1-star dependency worth it for a few hundred lines we could own outright?
5. What is the cost of a mis-send (tenant A's invoice arriving from tenant B's domain)? That number sets the testing and rollout bar.

Integration Approach

Stack fit — Best fit is a Laravel 10/11/12 app already on the Mail facade with a first-class Tenant model, credentials columns, and existing tenant-resolution middleware. Poor fit if most mail is dispatched from queued jobs with no tenant handle, or if we run serverless/Vapor with tight cold-start budgets.

Migration path

1. Branch spike: install, implement the contract on Tenant, wire resolveScopeUsing, and send to a sandbox inbox (Mailpit/Mailtrap).
2. Inventory every mail call site and classify as tenant-scoped or intentionally global.
3. Introduce our own thin wrapper (e.g. TenantMail::send()) rather than letting call sites bind directly to the package facade — makes fork-and-replace a one-file change.
4. Add encrypted credential storage plus a config-shape validator (required keys, allowed transports) before any tenant can submit credentials.
5. Roll out per-tenant behind a feature flag, keeping global config as the fallback until the pilot cohort is green.

Compatibility — Verify against our exact Laravel minor and PHP version; confirm behavior under config:cache and optimize. Test the synchronous path and the queued path independently, and check that ScopedMail::fake() coexists with existing Mail::fake() expectations. If we run Octane, add a concurrency test for cross-request config bleed.

Sequencing — (1) synchronous transactional mail for one pilot tenant; (2) admin self-serve credentials UI with save-time validation and a test send; (3) queued mail once scope rehydration is proven; (4) notifications and third-party package paths; (5) additional providers only after 1–3 are stable. Budget roughly 2–3 developer-days for integration and 2–4 weeks for production hardening (queue semantics, secrets, observability, deliverability plumbing).

Operational Impact

Maintenance — Low ceremony and low dependency weight, but effectively self-maintained. Pin the version, add a canary job against the next Laravel major, and encode the expected contract in our own tests so an upstream signature change fails loudly rather than silently.

Support — No vendor support, no security policy, one maintainer. We need an internal runbook: how to inspect a tenant's effective mail config, rotate a credential, and force-fallback a tenant to global. The package also provides no per-send audit trail, so we must log tenant id, transport, and from-address on every send ourselves.

Scaling — Config resolution is negligible next to an SMTP handshake, but per-tenant credentials multiply outbound connections and provider accounts. Connection pooling, per-tenant rate limits, and provider-side quotas (SES sandbox, per-domain sending caps) become real constraints and tend to surface at the worst moment. Credential storage grows linearly with tenants — plan key management and rotation early.

Failure modes

Ramp-up — A Laravel developer is productive in half a day from the README. The real ramp-up is tenancy and deliverability context: who the tenant is, which provider they use, and who controls their DNS. Assign a named owner for tenant email onboarding — that workflow, not the package, is the recurring operational cost. Recommendation: proceed to a timeboxed spike, but gate production on queue-context correctness, encrypted credentials, and per-send observability, and treat the dependency as vendorable code rather than a supported product.