Connect Email (Gmail)

This guide walks you through connecting a Gmail account to Pinchy so your agents can work with email — reading, searching, drafting, and sending messages.

The setup has two parts: creating an OAuth app in Google Cloud (one-time), then connecting the account in Pinchy.

Note

One app, many mailboxes. You register the Google OAuth app (Client ID and Secret) once, then connect as many Gmail mailboxes as you like through it. The app and the mailboxes have separate lifecycles — you manage the app in the Connected apps section, below the Integrations list where each mailbox appears. See Connect Email for the overview.

Prerequisites

• Pinchy is running with HTTPS enabled (see Lock Pinchy to a Domain)
• You're logged in as an admin in Pinchy
• A Google Cloud Console account (free — any Google account works)

Caution

Google OAuth requires HTTPS. The Add Integration wizard shows a warning and blocks the Google flow when Pinchy runs without HTTPS.

Part 1: Create a Google Cloud OAuth app

Google requires you to register your Pinchy instance as an OAuth application before users can sign in with Google. This is a one-time step per Pinchy installation.

1.1 Open Google Cloud Console and select a project

1. Go to console.cloud.google.com
2. In the top bar, click the project name (or Select a project if none is selected)
3. Create a new project (e.g. "Pinchy") or select an existing one

Tip

Create a dedicated project for Pinchy rather than reusing an existing one — it keeps credentials organized and makes it easy to revoke access later.

1.2 Configure the Auth Platform

Google Cloud uses the Auth Platform to manage OAuth consent screens and app identity. You need to set this up before creating credentials.

1. In the left sidebar, navigate to APIs & Services → OAuth consent screen

   Google redirects you to Auth Platform → Overview. If you see "Google Auth Platform not yet configured", click Get Started.

2. Under Branding, fill in:

   • App name — enter Pinchy (this name appears on the Google sign-in screen)
   • User support email — select your email address
   • Click Save

3. Under Audience, choose who can use this OAuth app:

   • Internal — your company uses Google Workspace (G Suite). Only people in your organization can connect — no Google review required. Recommended.
   • External — personal Gmail accounts, or no Google Workspace. Anyone with a Google account can connect. Read the note below before choosing this.

   Caution

   External + Testing mode: Google automatically puts new External apps into "Testing" mode. In this mode, refresh tokens expire after 7 days — which means the agent loses access to email every week and needs to be reconnected manually. To fix this, you must either switch to "Internal" (if you have Google Workspace) or publish your app after completing the setup.

1.3 Add Gmail scopes

Scopes define what data your OAuth app can access. You need to add the Gmail scopes that match the permissions you want to grant agents.

1. In the Auth Platform sidebar, click Data Access

2. Click Add or remove scopes

3. In the filter, search for gmail and add these scopes:

   • https://www.googleapis.com/auth/gmail.readonly — read and search emails
   • https://www.googleapis.com/auth/gmail.compose — create drafts and send emails
   • https://www.googleapis.com/auth/userinfo.email — identify the connected account

4. Click Update and then Save

Tip

If you only want agents to read email (no sending), you can skip the gmail.compose scope. You can always add it later if needed.

1.4 Add test users (External apps only)

If you chose External audience, Google restricts access to explicitly approved test users while your app is in Testing mode.

1. In the Auth Platform sidebar, click Audience
2. Under Test users, click Add users
3. Enter the Gmail address(es) of the accounts you want to connect to Pinchy
4. Click Save

Note

Test users see a warning screen ("This app isn't verified") before signing in. This is expected for apps in Testing mode — users can click through it. Once you publish the app, this warning disappears.

1.5 Create OAuth credentials

Now you create the actual Client ID and Client Secret that you'll enter in Pinchy.

1. In the Auth Platform sidebar, click Clients, then Create client (alternatively: APIs & Services → Credentials → Create Credentials → OAuth client ID)

2. Under Application type, select Web application

3. Give it a name (e.g. "Pinchy")

4. Under Authorized redirect URIs, click Add URI and paste the redirect URI shown in the Pinchy wizard (Settings → Integrations → Add Integration → Google, step 1)

5. Click Create

A dialog appears with your Client ID and Client Secret. Copy both values now — the Client Secret is only shown once. (If you lose it, you can create a new one in the credentials list.)

---

Part 2: Connect the account in Pinchy

1. Open the Add Integration wizard

   In Pinchy, go to Settings → Integrations and click Add Integration, then select Google.

   

2. Enter your OAuth credentials

   Paste the Client ID and Client Secret from Part 1 and click Save & Continue.

   Pinchy encrypts these credentials and stores them on your server — they never leave your infrastructure.

3. Connect a Google account

   Click Connect Google Account. Google's sign-in screen opens — sign in with the Gmail account whose email the agent should access.

   After signing in, grant the requested permissions. If your app is in Testing mode, you'll see a warning screen first — click Continue to proceed.

4. Verify the connection

   You're redirected back to Pinchy. The integration list now shows the connected Gmail address with a green "Connected" status.

For subsequent Google connections (a second Gmail mailbox), the OAuth credentials step is skipped — you go straight to "Connect Google Account". The app you set up in Part 1 is reused for every Gmail mailbox on this Pinchy instance.

---

Managing the app later

The Google OAuth app you set up in Part 1 lives in the Connected apps section of Settings → Integrations, below the list of connected mailboxes. You can update or reset it at any time — the app and the connected mailboxes are managed separately.

Edit the app credentials

Click Edit on the Google row to update the Client ID or Client Secret. The Client ID stays pre-filled and you can change it on its own. The Client Secret field starts empty — leave it blank to keep the stored secret, or type a new one to rotate it. Changes apply to every Gmail mailbox connected through this app.

Rotate the client secret

Google client secrets don't expire on a fixed schedule, but you may still want to rotate one — for example after a staff change or if you suspect it leaked. Rotating only the client secret keeps every mailbox connected: the existing refresh tokens stay valid, so agents keep working without interruption.

Changing the Client ID, on the other hand, points Pinchy at what is effectively a different app. The old refresh tokens no longer apply, so every mailbox must be reconnected afterward.

Tip

Keep the app on Published or Internal status. In Google's Testing mode, refresh tokens expire after 7 days and every mailbox disconnects weekly. Unused refresh tokens also expire after 6 months of inactivity even for a published app — a mailbox no agent has touched in half a year needs reconnecting.

Reset the app

Click Reset on the Google row to clear the stored credentials entirely. This is the deliberate way to remove an app — it stays configured until you reset it, even after you've removed its last mailbox.

Caution

Resetting the app disconnects every Gmail mailbox connected through it. The confirmation dialog tells you exactly how many mailboxes will be affected before you commit. Each one must be reconnected afterward. This can't be undone.

---

Part 3: Grant agent email permissions

A connection alone doesn't give any agent access. You must explicitly grant permissions per agent.

Note

Only shared agents have a Permissions tab. Personal agents can't be granted integration access — email permissions are a shared-agent feature.

1. Open the agent you want to connect to email

2. Click the gear icon to open Agent Settings

3. Select the Permissions tab

4. In the Email section, select the connected account and check the operations this agent may perform:

   • Read messages — list, read, and search emails
   • Create drafts — create draft emails (saved but not sent)
   • Send messages — send emails immediately (cannot be undone)

5. Click Save & Restart and confirm. Permission changes restart the agent runtime, so active chats are briefly disconnected.

Caution

Send messages is a powerful permission. The agent can send email from the connected account without human review. Consider using Create drafts instead — a human reviews and sends drafts manually.

---

Publishing an External app

If you chose External audience and want to remove the 7-day token expiry and the "This app isn't verified" warning, you can publish your app.

For apps that only use Gmail scopes, Google may require a security review before publishing. This process can take several weeks. An easier alternative for most Pinchy users is to switch to Internal audience (requires Google Workspace) — no review needed.

To publish an External app:

1. Go to Auth Platform → Audience
2. Under Publishing status, click Publish app
3. Follow the prompts — if your app uses restricted scopes (Gmail is restricted), Google will require a verification process

---

Test it

Open the agent's chat and try a few queries:

• "Show me my latest unread emails"
• "Search for emails from max@example.com about invoices"
• "Draft a reply to the last email saying we'll process it today"
• "How many unread emails do I have?"

---

Available tools

When email permissions are granted, the agent gets access to these tools:

| Tool | Permission required | Description | | ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | email_list | Read | List emails from a folder (INBOX, SENT, DRAFTS, TRASH, SPAM; defaults to INBOX). Supports filtering by read status. | | email_read | Read | Read the full content of a specific email by ID. Lists any attachments with their IDs. | | email_get_attachment | Read | Download an email attachment into the agent's workspace. | | email_search | Read | Search emails using structured fields: from, to, subject, text, unread, sinceDays, folder, limit (e.g. { from: "user@example.com", subject: "invoice", sinceDays: 7 }). text is a free-text match across sender, subject, and body — use it to find a phrase mentioned in the message content, like an invoice number. | | email_draft | Draft | Create a draft email. Can also create reply drafts with replyTo. | | email_send | Send | Send an email immediately. Can also send replies with replyTo. |

---

Token refresh

Google access tokens expire after about one hour. Pinchy automatically refreshes expired tokens in the background — no action required.

If a refresh fails permanently — the Google account revoked access, the refresh token expired after 7 days in Testing mode, or an unused token lapsed after 6 months — the mailbox's card in Settings → Integrations switches to a red "Authentication failed" state.

To recover, open the mailbox's … menu, click Reconnect, then Reconnect via Google in the dialog. This restarts the Google sign-in flow for that mailbox and keeps its existing agent permissions attached — you don't have to re-grant anything.

---

What's next

• Integrations — how connections and permissions work
• Agent Permissions — the full allow-list model