Gmail (OAuth)

The Gmail integration sends Frontmail templates from your own Gmail or Google Workspace mailbox through the Gmail API. Sent messages appear in your Sent folder, replies come back to your inbox, and recipients see a normal email from you.

Choose Gmail when you run a personal site, portfolio or small business and want form submissions and notifications to come from the address you already use – with no DNS setup if you use @gmail.com. It is not meant for volume: Google caps daily sending (see Limits) and there are no delivery webhooks. For transactional volume use Mailgun, Postmark, Amazon SES or Resend. See the services overview.

OAuth instead of app passwords

You can also connect Gmail via SMTP with an app password, but OAuth is safer: Frontmail never sees your password, the permission is limited to sending, and you can revoke it at any time in your Google Account.

Prerequisites

• A Gmail account (@gmail.com) or a Google Workspace user with Gmail enabled.
• For Workspace: your admin must allow third-party apps to access Google data, or explicitly trust Frontmail in Admin console → Security → Access and data control → API controls → App access control.
• Nothing else – no API key, no Google Cloud project.

Connect in Frontmail

1. Open Email services → Add service → Gmail.
2. Click Connect Gmail. You are redirected to Google.
3. Choose the account and review the consent screen. Frontmail asks for:
   • https://www.googleapis.com/auth/gmail.send – send email on your behalf. This is a send-only scope: Frontmail cannot read, search, delete or modify any email in your mailbox.
   • openid email – your email address, so the dashboard can show which account is connected and use it as the default From address.
4. Click Allow. Google redirects you back and the service is saved with the connected address shown.
5. Optionally set Max emails per second (default 2/s) and click Test connection, which refreshes the access token and checks that the gmail.send permission was granted.

What is stored: Frontmail stores the OAuth refresh token (and a short-lived access token), encrypted with AWS KMS envelope encryption. The access token expires after about an hour; Frontmail silently refreshes it before sending. The flow uses PKCE and always requests offline access, so re-connecting issues a fresh refresh token.

App verification

Frontmail’s production OAuth app is verified by Google for the gmail.send scope, so you see Frontmail’s name and no “unverified app” warning.

When the token stops working

Google invalidates a refresh token when you:

• revoke access in Google Account → Security → Third-party apps & services → Frontmail,
• change the Google account password (for Gmail scopes Google revokes existing tokens),
• don’t use the token for 6 months,
• or a Workspace admin removes the app’s access.

The next send or health check then fails with invalid_grant. Frontmail treats it as an auth error: the service is marked unhealthy, you get an email and a dashboard banner, and messages are held (or sent through the fallback service) until you click Reconnect on the service page. Reconnecting creates a new refresh token and releases held messages automatically.

Self-hosted / “Testing” OAuth apps

If you run Frontmail against your own Google Cloud OAuth client whose publishing status is Testing, Google expires refresh tokens after 7 days – the service will go unhealthy every week. Publish the app (and complete verification for the sensitive gmail.send scope) for tokens that last. This does not apply to the hosted frontmail.dev app.

DNS: SPF, DKIM and DMARC

• @gmail.com addresses: nothing to do – Google signs and authenticates the mail.
• Google Workspace on your own domain: publish Google’s records if you haven’t already:

; SPF
example.com.                    TXT  "v=spf1 include:_spf.google.com ~all"

; DKIM – generate in Admin console → Apps → Google Workspace → Gmail → Authenticate email
google._domainkey.example.com.  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…"

; DMARC
_dmarc.example.com.             TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

After publishing the DKIM record, click Start authentication in the Admin console. Tighten DMARC to p=quarantine / p=reject once reports look clean.

Note

Google’s own 2024 sender requirements for bulk senders apply to mail sent to Gmail users from anywhere – including Workspace. A contact form won’t reach the 5,000/day threshold, but SPF + DKIM + DMARC on your Workspace domain is still recommended.

From address: Gmail sends as the connected account. You can use another address only if it is configured as a Send mail as alias in Gmail settings; otherwise Gmail rewrites the From to the account address.

Regions

There are no regions – the Gmail API is global.

Sending limits

Google enforces per-user daily limits. Exceeding them blocks sending for up to 24 hours.

Account	Approximate limit
Consumer Gmail (@gmail.com)	~500 recipients per day
Google Workspace	~2,000 messages per day (lower during trial)
Gmail API	250 quota units per user per second; one send = 100 units

Frontmail therefore sends at most 2 messages per second through Gmail. When Google answers dailyLimitExceeded, Frontmail waits an hour between retries; if the limit persists, the message ends as failed and the credit is refunded.

Delivery tracking (webhooks)

Gmail has no delivery webhooks, so there is nothing to configure and no webhook URL on the service page. Frontmail knows only whether Google accepted the message (sent) or refused it (failed). Bounces arrive as normal “Delivery Status Notification” emails in your Gmail inbox, and they are not added to the Frontmail suppression list automatically. Opens and clicks are not tracked.

Common errors

• auth – the service is broken (token revoked/expired, invalid_grant, 401/403, Gmail not enabled for the Workspace user). The service is marked unhealthy; the owner gets an email and a dashboard banner. A fallback service on the template takes over; otherwise the credit is refunded and the message waits in the hold queue as held_service_error, sent automatically after you reconnect (re-checked on save and by the daily health check).
• permanent – this message can’t be sent (invalid recipient, message too large, 400 validation). Fallback service if configured, otherwise failed and refunded.
• transient – 5xx, rate/daily limits, timeouts. Retried with exponential backoff; after the last attempt failed and refunded.

Google response	Class	What to do
invalid_grant – Token has been expired or revoked	auth	Click Reconnect on the service page and grant access again.
401 – Invalid Credentials	auth	Usually fixed by the automatic token refresh; if it persists, reconnect.
403 – Insufficient Permission / insufficient_scope	auth	The gmail.send box was unticked on the consent screen – reconnect and allow sending.
403 – access blocked by the Workspace admin	auth	Ask your admin to trust Frontmail in API controls.
400 failedPrecondition – Mail service not enabled	auth	The Workspace user has no Gmail licence; enable Gmail or connect another account.
400 invalidArgument – Invalid To header	permanent	See invalid recipient.
413 / 400 – message too large	permanent	Reduce attachment size (Gmail’s limit is 25 MB).
429 / 403 rateLimitExceeded, userRateLimitExceeded, dailyLimitExceeded	transient	Slow down or wait for the daily limit to reset; consider a transactional provider.
500 / 503 backendError	transient	Google outage – Frontmail retries.

Checklist

• Connected with Connect Gmail; consent granted for sending email
• Workspace: Frontmail allowed in API controls (if restricted)
• Workspace on own domain: SPF include:_spf.google.com, DKIM google._domainkey, DMARC
• Template From = the connected address or a configured Send mail as alias
• Test connection passes
• Daily volume well below Google’s limits
• Fallback service configured on important templates in case the token is revoked