feat(email): native Gmail API mail provider for GCP self-hosting

[waleedlatif1]

Summary

• Adds Gmail as a fifth transactional mail provider so self-hosters on GCP can send app email natively (verification, invites, notifications). Priority order becomes Resend → AWS SES → SMTP → Azure Communication Services → Gmail
• GCP has no first-party SES/ACS equivalent — the Google-native path is the Gmail API: a service account with domain-wide delegation (GMAIL_CREDENTIALS_JSON) impersonates a Workspace sender (GMAIL_SENDER) with the gmail.send scope
• Full parity with the other providers: html+text multipart, attachments, replyTo, and the unsubscribe headers — the raw RFC 822 message is built with nodemailer's MailComposer (already a dependency) and posted to the messages.send media-upload endpoint (message/rfc822, up to ~35 MiB)
• Misconfiguration (one var missing, invalid JSON) logs a warning and skips the provider, matching the SMTP provider's tolerant behavior
• Docs: Gmail section in environment-variables.mdx (incl. the Workspace SMTP relay alternative via the existing SMTP provider), .env.example, helm values.yaml + values.schema.json, and a mail section in values-gcp.yaml

Type of Change

• New feature

Testing

• 8 new tests for the Gmail provider: factory gating (missing/partial/invalid config), JWT impersonation config, raw-MIME construction (To/From/Reply-To/List-Unsubscribe/attachments asserted on the actual RFC 822 payload), endpoint/headers, token-failure and API-error paths
• Full messaging suite passes (91 tests), typecheck clean, helm lint + helm template with values-gcp.yaml render correctly

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jul 17, 2026 7:30pm

[cursor]

PR Summary

Medium Risk
Touches transactional email delivery and handles service-account credentials; misconfiguration is tolerated, but wrong success handling could duplicate mail via fallback—mitigated by explicit 2xx-empty-body handling and tests.

Overview
Adds Gmail as a fifth transactional mail provider for self-hosted GCP deployments, extending auto-detection to Resend → AWS SES → SMTP → Azure ACS → Gmail.

The new provider uses a service account (GMAIL_CREDENTIALS_JSON) with domain-wide delegation to impersonate a Workspace user (GMAIL_SENDER), builds RFC 822 via nodemailer's MailComposer, and posts to the Gmail API media-upload send endpoint. Partial or invalid config is skipped with warnings (same pattern as SMTP). Successful 2xx responses with empty bodies are treated as success so the mailer fallback chain does not duplicate sends.

GMAIL_CREDENTIALS_JSON and GMAIL_SENDER are wired through env schema, .env.example, self-hosting docs (including Workspace SMTP relay as an alternative), and Helm values.yaml / schema / GCP example.

^{Reviewed by Cursor Bugbot for commit 193c834. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds Gmail API support as a transactional email provider. The main changes are:

• Service-account authentication with Workspace sender impersonation.
• MIME email composition with attachments, reply-to, and unsubscribe headers.
• Gmail configuration in the app environment and Helm chart.
• Setup documentation and provider tests.

Confidence Score: 5/5

This looks safe to merge.

• Successful Gmail responses now remain successful when the response body is empty or malformed.
• The mailer stops after Gmail accepts the message, avoiding an incorrect failure result.
• Current callers tolerate a successful result without a provider message ID.
• Tests cover the updated response behavior.

Important Files Changed

Filename	Overview
apps/sim/lib/messaging/email/providers/gmail.ts	Adds Gmail authentication, MIME composition, API submission, and tolerant handling of successful responses without valid JSON bodies.
apps/sim/lib/messaging/email/providers/gmail.test.ts	Tests configuration gating, delegated authentication, MIME payloads, recipients, attachments, and Gmail response paths.
apps/sim/lib/messaging/email/providers/index.ts	Registers Gmail after the existing email providers.
apps/sim/lib/messaging/email/types.ts	Adds Gmail to the supported provider-name union.
apps/sim/lib/core/config/env.ts	Adds optional Gmail credentials and sender environment variables.
helm/sim/values.schema.json	Adds Gmail settings to the Helm values schema.

_{Reviews (2): Last reviewed commit: "fix(email): review round 1 + audit harde..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 193c834. Configure here.}