Skip to main content

Gmail

Connect a Google account so assistants can read, search, and (when you allow it) send mail from that mailbox. Gmail is a per-member connection: each workspace member connects their own Google account. Workspace admins enable the feature; members authorize their own OAuth grants.

This is separate from a workspace inbox. Inboxes receive mail at a Gravity Rail address. The Gmail connection reads mail that already lives in the Google account you connect.

Before You Start​

You'll need:

  1. The Gmail feature enabled on your workspace. If you don't see Gmail in the App Connections directory, ask your Gravity Rail administrator to turn on the Gmail feature.
  2. A Google account whose mailbox you want assistants to read. You can connect more than one Google account if you work across several organizations.
  3. If the account is on Google Workspace (for example you@radiusclinic.com), a domain admin must allow Gravity Rail first. Personal @gmail.com accounts do not need this. See Google Workspace Accounts.

Connecting Your Google Account​

  1. Go to App Connections and open the Directory tab.
  2. Find Gmail (Google category) and click Install.
  3. Click Connect — you'll be redirected to Google's authorization page.
  4. Sign in with the Google account whose mailbox you want assistants to read.
  5. Review and approve the requested permissions (see Required Permissions below).
  6. You'll be redirected back to your workspace. The new connection appears on the Active tab under Platform Integrations.

Connecting Multiple Google Accounts​

  1. On the Active tab, open the Gmail connection.
  2. Click Add account and repeat the OAuth flow with the second account.
  3. Assistants see all connected accounts when listing available connections.

Connecting During a Chat​

If the workspace has inline connect enabled and you don't yet have a Gmail connection, an assistant may prompt you to connect from the chat. Click the Connect Gmail button to launch the OAuth flow without leaving the conversation.

Required Permissions​

Gravity Rail requests the following Google OAuth scopes when you connect:

ScopeWhy it's needed
gmail.readonlySearch threads and read message content
gmail.sendSend mail from the connected account when the ability is read-write
gmail.modifyReserved so you can authorize once if label or state changes are added later
userinfo.email, userinfo.profile, openidIdentify which Google account is connected

The assistant's tools follow the Gmail ability's access mode in Gravity Rail. A read-only ability cannot send or modify mail even though those scopes were requested at connect time.

What Assistants Can Do​

Once your Google account is connected, assistants with the integration:gmail ability can:

ToolWhat it does
List connectionsShow which Google accounts you have connected
Check GmailSearch the mailbox for matching threads
Read a threadOpen a thread and read its messages
Send emailSend a message from the connected account (read-write access mode only)
Reconnect accountRe-authorize a connected account if the token has expired

Managing Your Connection​

Viewing Connected Accounts​

Go to App Connections → Active tab and open Gmail. Each row shows the connected Google email address and connection status.

Reconnecting an Expired Account​

If your OAuth token expires or is revoked, the connection shows a Reauthorize Required badge:

  1. Open the Gmail connection on the Active tab.
  2. Click Reauthorize next to the affected account.
  3. Complete the Google OAuth flow again.

Alternatively, ask an assistant to reconnect: "Reconnect my Gmail account."

Removing an Account​

  1. Open the Gmail connection on the Active tab.
  2. Click the action menu next to the account you want to remove.
  3. Choose Disconnect.

To remove the integration entirely, choose Delete from the connection's action menu. This removes all connected Google accounts and their stored tokens.

Also revoke from Google. Removing the connection in Gravity Rail deletes our copy of the OAuth token, but Google keeps its own record of the grant. To fully revoke access, visit myaccount.google.com/permissions and remove the Gravity Rail app.

Troubleshooting​

"This app is blocked" or admin_policy_enforced​

The Google account is on a Workspace domain that blocks unverified third-party apps. This is the usual reason a personal Gmail account connects and a company account (@radiusclinic.com, @yourhospital.org) does not. Send Google Workspace Accounts to your Google Workspace admin and retry after they mark the Gmail client as Trusted.

Sign-in with Google can still work on the same domain. Sign-in only asks who you are; Gmail asks to read the mailbox.

"Reauthorize Required" badge​

Google has revoked or expired the access token. This happens when:

  • The token hasn't been used for six months (Google's inactivity policy)
  • You changed your Google account password
  • You manually revoked access in Google's account settings
  • An admin in your Google organization restricted third-party app access

Open the connection and click Reauthorize to re-run OAuth.

Assistant can't find a message​

  • Confirm the message is in the Google account you connected — assistants only see that mailbox.
  • Try a more specific subject, sender, or date in your prompt.
  • Recently arrived mail can take a moment to appear in search.

"Gmail not available" or missing from the Directory​

The Gmail feature is not enabled on your workspace. Ask your Gravity Rail administrator to enable it.