Skip to content
AlumiaDocs

Search docs

Find pages, headings, and concepts. Press ⌘K or Ctrl+K to toggle.

Connect Gmail

Wire Gmail through OAuth, attach it to an agent, and have the agent read your inbox.

Open in ChatGPTOpen in Claude

Gmail is one of the most-used connectors. This walkthrough takes you from "no Gmail" to an agent that summarises your unread inbox.

1. Open the connector catalog

Navigate to /<orgSlug>/connectors. The catalog lists every connector slug grouped by category. Search for gmail (it's under Google Workspace).

2. Click Connect

Open the Gmail entry and click Connect. The OAuth flow opens Google's consent screen in a normal new tab — not a popup with popup=1 or fixed dimensions. Sign in with the Google account whose mailbox you want the agent to access. Grant the requested scopes; deny anything you don't need.

When you finish consent, the tab returns to Alumia. The originating page refreshes via BroadcastChannel — you don't need to switch tabs manually. The connector now shows in the Connected list with its account email.

3. Verify the connection

Still on /<orgSlug>/connectors, the Gmail card has a status badge. Connected means OAuth completed and the credential is encrypted at rest. If you see Auth failed, redo step 2.

4. Attach Gmail to an agent

Open /<orgSlug>/agents and the agent you want to give inbox access to. In the Tools section, scroll to the Gmail group. The connector exposes its operations as individual tools — common ones include:

  • gmail.list_messages — list message metadata.
  • gmail.search — query with Gmail's search syntax.
  • gmail.get_message — fetch a single message body.
  • gmail.send — send mail (separate scope; only enable if needed).

Enable the operations the agent should use. Leave the rest off. Save.

5. Ask the agent about your inbox

Open /<orgSlug>/lab, pick the agent in the prompt bar dropdown, and send:

"Summarise my unread inbox from the last 24 hours. Group by sender."

What happens:

  1. The agent picks gmail.search with a query like is:unread newer_than:1d.
  2. It calls gmail.get_message for each result.
  3. It synthesises a grouped summary and streams it back.

The tool calls render on the canvas as steps under the agent's session — you can click each one to inspect arguments and the raw return.

6. Scope it down

If the summary is good but the agent had access to too much, edit the agent and disable any operation it didn't need. You can also tighten the OAuth scopes from Google's account permissions page. Both layers compose — see Tool calling for how scoping works.

What can go wrong

  • OAuth token expired. The connector auto-refreshes. If refresh fails (revoked access, password reset), the status flips to Auth failed — click Reconnect to redo OAuth.
  • Insufficient scopes. If the agent calls gmail.send and you only granted read scopes, the call returns an auth error. Reconnect with the broader scope.
  • Rate limits. Gmail's API enforces per-user quotas. The connector surfaces these as standard tool errors; the agent will usually retry or back off.

For more, see Troubleshooting.