Connect Gmail

Solutioneer uses the Composio gmail toolkit to read email threads and attachments during discovery. It is read-only — Solutioneer does not send email from your account.

Prerequisites

• A Composio API key in .env.
• A Google account with access to the mailbox you want Solutioneer to read.

What gets connected

The gmail toolkit bundles read-only Gmail access under one OAuth connection. After connecting, Solutioneer can call these specific tool slugs:

• GMAIL_FETCH_EMAILS — fetch emails matching a query.
• GMAIL_FETCH_MESSAGE_BY_THREAD_ID — fetch messages in a specific thread.
• GMAIL_LIST_THREADS — list recent threads.
• GMAIL_GET_ATTACHMENT — fetch an attachment from a message.

All four are read-only.

How to connect

The normal flow runs inside Codex during an ingestion request:

1. Ask Solutioneer to pull from Gmail. For example: “Ingest the thread with acme-health.com from my Gmail into a fact sheet.”
2. Codex verifies that COMPOSIO_API_KEY is present.
3. Codex checks whether the gmail toolkit is connected.
4. If it is not, Codex offers Connect now / Skip.
5. Connect now opens the Composio hosted login page in a browser tab.
6. You complete the Google OAuth flow and approve the Gmail scopes.
7. Codex polls the connected account until it becomes ACTIVE.
8. Once active, Codex reads the requested messages.

If browser tooling is unavailable, Codex provides the login link in chat and waits for you to finish the flow.

Connect from the Composio dashboard

If you prefer to connect ahead of time:

1. Open the Composio dashboard.
2. Go to Connections (or Toolkits).
3. Find the gmail toolkit.
4. Click Connect and complete the Google OAuth flow for Gmail.
5. Confirm the connection shows as Active.

Which skills read from Gmail

• Discovery Context Ingester — the primary consumer. Email threads and attachments are normalized into the fact sheet with composio://gmail/... provenance markers.

Confirmation rules

Ingestion is triggered explicitly. Codex will not read from Gmail unless you name Gmail as a source or reference specific email context. Once the toolkit is connected, subsequent ingestion runs do not re-prompt for consent.

Scope notes

The Gmail OAuth flow requests the narrowest scopes needed for read-only access. Solutioneer never sends email, modifies labels, or deletes messages.

Troubleshooting

• No messages returned. Narrow the query, or try a broader search. Gmail’s search is label-aware; messages under custom filters may not match default queries.
• Attachment download fails. Some attachment types (for example, Google Workspace native files) require export rather than raw download. Solutioneer falls back to the corresponding export tool when appropriate.
• Connection stuck in pending. Re-open the Composio link and finish sign-in. Codex polls for up to five minutes before timing out.
• Wrong account. Each Google OAuth flow is tied to the account you sign in with. Disconnect the toolkit and reconnect with the right mailbox.

See Troubleshooting for more.