Connecting Gmail

Signing in is not connecting a mailbox#

Both use Google, and they are different acts with different consequences. Signing in proves who you are to Connect — it is the only sign-in there is, because there is no password login. Connecting a mailbox grants Connect standing access to the mail in a particular Google account, on behalf of a workspace, until that grant is withdrawn.

You can therefore sign in as yourself and connect a mailbox that is not yours — a shared support address, for instance — provided you can complete Google's consent for it. Revoking the mailbox grant does not sign you out, and signing out does not disconnect the mailbox.

The path#

1. Open #/mailboxes, add a mailbox, and choose Google.

   Result Add-a-mailbox asks one question — which provider — and asks it identically for both audiences.

2. Complete Google's consent screen for the account whose mail you want Connect to work.

   Result Google shows exactly what is being asked for. That screen, at the moment you see it, is the authority on the permissions granted — see Gmail OAuth scopes and why each is asked for.

3. Google returns to Connect and oauth.store_tokens writes the result.

   Result The tokens land in the mailbox's config, sealed by settings_store on save. Nothing echoes a credential back to a screen afterwards, including to the person who granted it.

4. Give the new row a role, a signature and its autonomy, then let the first sync run.

   Result History is read in and the row begins reporting health. Until a first pass completes, 'connected' is all the screen can honestly say.

The Owner could not do this, and now can#

This is one of the three email defects worth documenting, because it is the exact shape the two-audience rule exists to catch. Every customer workspace could connect a Google account through the customer wizard. The Owner could not: the handler behind 'Connect a Google account' existed and worked, and nothing on any Owner screen called it. A capability that is reachable by one audience and unreachable by the other is a defect even when both share the implementation, and it is invisible in the code — the function is right there.

The fix was not a second flow. Add-a-mailbox now asks the same question the customer's wizard asks, and the Owner's Gmail path falls back to the platform's own Google client, so there is one route in and one place where policy lives. One implementation, two audiences is the longer argument for why the second implementation is never the cheaper option.

What the connection can do afterwards#

A write-back failure never blocks a reply. Marking a message read or applying a label is bookkeeping on Google's side; if it fails, the reply has still gone and the failure is reported as itself rather than as a send problem. That ordering is deliberate — the alternative is a workspace where a labelling permission quietly stops customers being answered.

When it stops working#

The grant was revoked at Google

Someone removed Connect from the Google account's connected apps. Reconnect through the same path; the existing threads and contacts are untouched.

The password changed or a security event occurred

Google may invalidate the refresh token. The verdict on the row is a health verdict, not a configuration error — Mailbox health names it.

The mailbox authenticates and returns nothing

That is a quiet mailbox, which is a signal rather than a fault.

The row vanished from the list

Suspect an empty workspace stamp before reconnecting, because reconnecting is what turns one invisible row into two rows for one inbox.

Questions#

Related#

• Gmail OAuth scopes and why each is asked for
• Gmail history sync
• Writing back to Gmail
• Mailboxes
• OAuth 2.0
• Gmail API
• One implementation, two audiences