Gmail integration

Summary

Unified E box is an external OAuth application. Each member connects their own personal Gmail account through Google’s official consent flow and can withdraw that access at any time. We request three scopes. Two of them are classified by Google as sensitive and one as restricted.

Scopes we request

Each scope below is requested at the moment a member connects a mailbox, and is shown to them by Google before they approve. The classifications are Google’s own, taken from the published Gmail API scope reference.

Scopes we deliberately do not request

Minimum scope is a design constraint, not an afterthought. These are permissions a mail application might plausibly ask for, and the reason we do not.

The authorization flow, step by step

1. A member selects Connect Gmail inside the workspace. We create a single-use, server-side state token bound to that member, which expires in ten minutes.
2. We redirect the member to Google’s consent screen with the three scopes listed above, requesting offline access so that background sync can continue without re-prompting.
3. Google shows the member which permissions are being requested and for which account.
4. The member approves or denies. If they deny, no tokens are issued and nothing is stored.
5. On approval, Google redirects back with an authorization code. We verify the state token, reject anything replayed or expired, and exchange the code for tokens.
6. We check that the grant actually includes the scopes the product needs. If Google returned a partial grant, we reject the connection rather than operate with a half-working mailbox.
7. We call oauth2.userinfo.get once to learn which mailbox just authorized, so the tokens are bound to the correct account record. This is the only trustworthy source of that identity.
8. Tokens are encrypted with AES-256-GCM and stored. The initial sync begins, and a Gmail watch is registered so future changes arrive as notifications.

How synchronization works

After the first sync, Unified E box does not repeatedly download the mailbox. It registers a Gmail watch and receives a notification when the mailbox changes, then asks Gmail for just the history since the last known point using users.history.list. This keeps our request volume proportional to actual activity rather than to the number of connected accounts, and it respects Gmail API usage limits.

Gmail watches expire after seven days, so a scheduled job renews them. If a member revokes access at Google, the next refresh fails, and we mark the account as requiring re-authorization and stop calling the Gmail API for it.

What we store

We store a working copy of the synced mail so the interface can render and search it quickly. The table below is a complete description of the Gmail-derived data we retain.

What we write back to Gmail

There are exactly five ways Unified E box changes anything in a connected Google account.

• Read state. When a member marks a conversation read or unread, we add or remove Gmail’s built-in UNREAD label on that thread.
• Stars. When a member stars or unstars a conversation, we add or remove Gmail’s built-in STARRED label on that thread.
• Drafts. While a member writes an email, we save it in their Gmail Drafts with users.drafts.create and keep it current with users.drafts.update. When they send or discard it, we remove that draft with users.drafts.delete. We only touch drafts we created.
• Sending. When a member writes a reply or a new message and submits it, we send it through users.messages.send from their own connected account.
• Calendar events. When a member creates an event on the Calendar page, we add it to that account’s primary Google Calendar with calendar.events.insert, inviting the guests they list. We never change or delete existing events.

We do not delete mail, move it to trash, archive it in Gmail, create or modify label definitions, or alter mailbox settings. The scopes we hold do not permit permanent deletion, and we did not request one that would.

Disconnecting

A member can disconnect a mailbox from the Accounts page at any time. When they do, we ask Google to revoke the refresh token and we delete the stored credentials outright. After that we cannot call the Gmail API for that mailbox at all. They can equally revoke us from their Google Account permissions page, which has the same effect on our access.

Limited Use

Unified E box’s use of information received from Google APIs adheres to the Google API Services User Data Policy, including the Limited Use requirements. In practice that means Gmail data is used only to provide the features described on this page, it is not transferred except as needed to run those features or to meet a legal obligation, it is never used for advertising, and it is never sold.

Human access to message content

Our staff do not read members’ Gmail message content. The narrow exceptions are the ones the policy allows: when a member explicitly asks us to look at a specific message to resolve a support problem, when it is necessary to investigate a security incident or abuse, or when we are legally required to. Any such access is limited to what the situation requires.

Verification status

Because gmail.modify is a restricted scope, this application is subject to Google’s OAuth verification process, which includes an independent security assessment for applications that keep restricted-scope data. We have designed the application to meet those requirements and are submitting it for review. We do not claim to be approved, verified, or certified by Google, and we will not describe ourselves that way unless and until that status is actually granted.

Reviewers may also find the OAuth review notes useful; they collect the scope justifications, the demo walkthrough, and our contact details in one place.