Connect a Gmail inbox

The inbox assistant reads a connected mailbox, drafts replies, and waits for you to review them. This page covers connecting Gmail — first the two minutes it takes as a user, then the one-time Google Cloud setup a self-hosted deployment needs.

Nothing is sent from your mailbox without you approving it, and an inbox can be set to never send at all.

Connect your mailbox

If your deployment already has Google credentials configured, this is the whole process.

1. Open Inbox assistant and go to Settings.
2. Choose Connect Gmail.
3. Pick the Google account whose mail you want the assistant to work on.
4. Approve the permissions Google lists.
5. You will land back in Whoa Flow with a confirmation naming the address that was connected.

The new inbox appears in the list with its own settings — tone, signature, standing instructions, model, page size, and send controls.

If Connect Gmail is greyed out, the deployment has no Google credentials yet. That is the setup described further down.

What the assistant can access

Whoa Flow asks Google for two permissions:

• Read your mail — to list threads and read the conversation it is drafting a reply to.
• Create drafts and send email — to put an approved reply into your Gmail drafts, or to send it when you explicitly choose to.

Access tokens stay on the server and are never exposed to the browser. You can revoke access at any time from your Google account permissions, and disconnecting the inbox in Whoa Flow removes it along with its drafts.

Keep replies as drafts

New inboxes create Gmail drafts rather than sending, and sending always takes a second confirming click. To remove the possibility entirely, open the inbox in Settings and turn Allow sending off. The approve action then only ever writes a draft into Gmail for you to read and send yourself.

This is the setting to use while you are deciding whether you trust the drafts.

Connect more than one Gmail account

Choose Connect Gmail again and pick a different Google account. Google shows the account chooser every time, so a second account needs no signing out.

Each mailbox is separate: its own tone, signature, standing instructions, model, and send controls. The address you sign in to Whoa Flow with does not have to match any of them — you might sign in as you@company.com and connect support@ and sales@.

Set up Google credentials (self-hosted)

A self-hosted deployment needs its own Google OAuth client. This is a one-time job for whoever runs the instance, not something each user does.

1. Create a project and enable the API

1. Create or select a project in the Google Cloud console.
2. Go to APIs & Services → Library, search for Gmail API, and enable it.

Skipping the second step is the most common mistake. The connection appears to work and every attempt to read mail then fails.

2. Configure the consent screen

Set the user type to External, fill in the app name and support email, and under Audience keep the app in Testing while adding each Gmail address you plan to connect as a test user.

Gmail permissions are classed as sensitive by Google, so an app in production needs Google's verification review. Testing mode skips that entirely, at the cost of a limit on test users and a consent screen that expires periodically and has to be re-approved.

Testing mode also shows an "unverified app" warning during consent. Choose Advanced → Go to (unsafe) to continue. That is expected here, because the app is your own.

3. Create the OAuth client

Under Credentials, create an OAuth client ID of type Web application, with this authorized redirect URI:

https://your-domain.example/api/auth/callback/google

Use http://localhost:3000/api/auth/callback/google when running locally — Google allows plain HTTP for localhost. The URI has to match exactly, including the scheme and any trailing path; a mismatch shows up as redirect_uri_mismatch.

4. Add the credentials and restart

Put the client id and secret in the deployment's environment:

GOOGLE_CLIENT_ID=<...>.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-<...>

Restart the app. Whoa Flow registers the Google provider only when both values are present, so a missing one leaves Connect Gmail disabled with no other symptom. Confirm the running process actually received them if the button stays greyed out — an environment variable exported in the surrounding shell will take precedence over a value in a .env file.

Troubleshooting

Connect Gmail is greyed out. The server has no Google client id and secret, or it has not been restarted since they were added.

redirect_uri_mismatch. The redirect URI registered in Google Cloud differs from the one the app used. It is built from the app's own public URL, so it must match that origin exactly.

access_denied. The Google account is not on the consent screen's test user list while the app is in Testing.

Reads fail with a permissions error. The Gmail API is not enabled on the project, or the Testing-mode consent has expired and needs re-approving.

What happens next

Once an inbox is connected, open a thread and choose Draft reply. The assistant reads the conversation and writes a reply for you to edit, discard, or approve. It is told not to invent order numbers, prices, dates, or commitments, and not to promise work on your behalf — when something is missing it should ask rather than guess.

Every draft is yours to change before anything leaves the mailbox.