Google Mailer Laravel Package

Technical Evaluation

What the package actually is symfony/google-mailer is a thin transport bridge, not a mailer and not a Laravel package. It supplies GmailTransport (plus a transport factory) that lets Symfony Mailer deliver messages through the Gmail REST API using a Google\Client instance. It does not provide: OAuth consent flow, token storage/refresh, retry policy, bounce/complaint handling, templating, or queueing. Those remain our responsibility.

Architecture fit

• Laravel ≥9 sends mail through symfony/mailer, so the underlying integration point exists. There is no first-party Laravel gmail driver; we must register a custom transport via Mail::extend() and construct GmailTransport ourselves.
• Fits cleanly only when the product requirement is "mail must originate from a Google identity" (per-user Gmail/Workspace mailbox, Sent-folder visibility, Workspace deliverability). If the requirement is just "send transactional email reliably," this is the wrong tool — an ESP (SES/Postmark/Mailgun/Resend) or plain SMTP is cheaper to operate.
• The bridge is stateless and small, so it composes well with Laravel queues, Mail::mailer('gmail') routing, and per-tenant mailer configuration.

Integration feasibility Technically straightforward: one service provider, one config block, one credential source. Operationally non-trivial: the credential lifecycle (OAuth client, refresh tokens, revocation, scopes) and Google's quota/verification regime dominate the effort, not the code.

Technical risk

Key questions for engineering/product

1. Is Gmail-identity sending a product requirement (user's own mailbox, Sent-folder proof) or an infrastructure shortcut?
2. One shared Workspace sender, or per-user/per-tenant OAuth connections? This changes the design by an order of magnitude.
3. Expected volume and burst profile vs. Gmail's per-user and per-day limits?
4. Who owns token encryption, rotation, revocation detection, and offboarding?
5. Do we need bounce/complaint feedback? If yes, Gmail alone is insufficient.
6. Can we absorb Google verification (and possibly CASA) as a release dependency?
7. What is the fallback path if Google changes scopes or denies verification?

Integration Approach

Stack fit Laravel 9+ only (Symfony Mailer era). PHP floor follows the bridge branch: 8.1 for the 6.4 line, 8.2 for the 7.x line. Verify against composer show symfony/mailer before requiring.

Compatibility matrix (validate at install time)

Pin the bridge to the same minor as symfony/mailer; do not let Composer resolve a bridge major that outruns the mailer.

Migration path (from SMTP or an ESP)

1. Introduce gmail as an additional mailer alongside the existing one; never replace in place.
2. Route a single low-risk notification class to gmail behind a config flag.
3. Register the transport in a dedicated MailServiceProvider:

Mail::extend('gmail', function (array $config) {
    $client = new Google\Client();
    $client->setClientId($config['client_id']);
    $client->setClientSecret($config['client_secret']);
    $client->setAccessToken($config['access_token']);   // refreshed/persisted by us
    $client->setScopes([Google\Service\Gmail::GMAIL_SEND]);
    return new Symfony\Component\Mailer\Bridge\Google\Transport\GmailTransport($client);
});

4. Add a gmail entry under config/mail.php mailers, driven by env vars.
5. Keep MAIL_MAILER and per-mailer routing as the rollback lever; a single env change reverts traffic.
6. Expand class-by-class only after two weeks of clean error rates.

Sequencing

• Phase 0 – Decision (1 week): confirm the Gmail-identity requirement; if absent, stop and use an ESP.
• Phase 1 – Spike (2–3 days): system Workspace account, one queued Mailable, verify send, measure latency, confirm quota headroom.
• Phase 2 – Credential plumbing (1–2 weeks): encrypted token store, refresh-before-send, invalid_grant handling, account-reconnect UX, audit log.
• Phase 3 – Hardening (1–2 weeks): rate limiter + queue backoff, dedupe keys, Google error → app error mapping, dashboards/alerts on auth-failure and quota-consumption rates.
• Phase 4 – Compliance (parallel, calendar-bound): Google OAuth verification submission; CASA assessment if applicable.
• Phase 5 – Cutover: per-mailer routing rollout, then retire the old path.

Testing note: GmailTransport cannot be captured locally — use log/array transports in tests and a dedicated Google test tenant for integration tests.

Operational Impact

Maintenance Low code churn (the bridge is a few hundred lines maintained by the Symfony core team, MIT). Real maintenance load is elsewhere: google/apiclient upgrades, Symfony major bumps riding on Laravel upgrades, and OAuth policy changes from Google. Budget one planned upgrade per Laravel major plus ad-hoc work when Google deprecates an auth flow. Run composer audit and pin the bridge exactly.

Support Failure tickets will cluster into four buckets, and support runbooks should mirror them:

1. Auth — token expired/revoked, scope removed, admin disabled the app → user-facing "reconnect your Google account," never a silent drop.
2. Quota — 429/rateLimitExceeded/dailyLimitExceeded → queue backoff plus a visible "delayed" state, not a hard failure.
3. Message — oversize attachments, blocked content, RFC violations → validate at compose time.
4. Platform — Google outage, network → retry, then dead-letter with alerting.

Without a bounce/complaint feed, support will absorb deliverability questions manually. Staff for that or add a supplementary provider.

Scaling

• Per-user model: throughput scales with connected users (each carries their own quota), but the product must tolerate partial availability when individual accounts disconnect. Engineering cost scales linearly with tenant onboarding UX.
• Single-account model: hard-capped by Workspace daily limits and per-user rate limits; unsuitable for bursty transactional traffic (password resets, digests) at any real volume.
• Expect several hundred milliseconds per send (HTTPS + token refresh) versus near-instant SMTP handoff; use queue workers with bounded concurrency and jittered backoff.
• No native batching in the transport; treat send throughput as a capacity-planning input, not an assumption.

Failure modes to instrument

• Refresh-token revocation storm after a Google policy change or admin action.
• Token-refresh thundering herd at worker start; cache access tokens with expiry skew.
• Clock skew causing premature expiry.
• Duplicate sends after timeout-retry (no idempotency key).
• Quota exhaustion on the 1st of the month / after a marketing blast.
• Silent degradation if errors are swallowed by the queue's failed() handler.

Ramp-up

• Senior Laravel engineer: ~1–2 days to a working transport, ~2–4 weeks to production-grade per-user OAuth (tokens, revocation UX, rate limiting, observability).
• Non-engineering: Google verification is calendar-bound (weeks, variable) and may carry a recurring CASA assessment cost — treat as a launch gate, not a ticket.
• TPM recommendation: adopt only if Gmail-identity sending is a stated product requirement; otherwise reject in favor of an ESP and revisit if the requirement appears. If adopted, mandate the dual-mailer rollout with an env-level rollback and make Google verification a tracked release dependency from day one.