How Postbox connects to Gmail
Last reviewed
Postbox never sees your Gmail password. Each mailbox is connected through Google’s own consent screen using the OAuth 2.0 authorization-code flow with PKCE, and what Google hands back is a revocable token — encrypted with AES-256-GCM before it is stored and decrypted only server-side, to call Gmail on your behalf.
The connection, step by step
- You create a Postbox account. Email and a password, or one tap with Google. This account exists only to hold your connections; it is never a Gmail password, and Postbox has no field to type one into.
- Postbox sends you to Google. Choosing "Connect a mailbox" builds an authorization URL and redirects you to Google. The request uses the authorization-code flow with PKCE: a random verifier is generated, its SHA-256 hash is sent as the challenge, and only the original verifier can redeem the code that comes back.
- You approve on Google’s own screen. Google shows you which permissions are being requested and which account you are granting them for. Nothing about this screen is controlled by Postbox. If you decline, nothing is stored and no connection is made.
- Google returns a code, and Postbox exchanges it. Google redirects back with a single-use authorization code. The server exchanges it with Google for an access token and a refresh token. This exchange happens server-side, so the code and the tokens never pass through your browser.
- The tokens are encrypted before storage. Both tokens are encrypted with AES-256-GCM before they are written to the database, using a key held only in the server environment. Your user id and the purpose of the record are bound into the encryption itself, so a row copied into another account will not decrypt.
- Gmail is called on your behalf. From then on the server decrypts a token in memory only, calls the Gmail REST API, and returns the result to your browser. The decrypted token is never sent to the browser, and a test asserts that it is not.
Exactly what is requested, and why
| Scope | What it allows | Why Postbox needs it |
|---|---|---|
gmail.modify | Read messages, send mail, add and remove labels. Cannot permanently delete. | The combined inbox, search, replying, and star/archive/read written back to Gmail. |
openid, email, profile | Your Google account id, address and display name. | To label the mailbox you just connected, and to tell two connected accounts apart. |
The full string is https://www.googleapis.com/auth/gmail.modify — you can check it against the consent screen Google shows you. There is one Gmail scope and no others. Postbox does not request access to Drive, Calendar, Contacts or anything else.
gmail.modify is deliberately not the narrowest scope that exists. A read-only scope would be safer on paper and would make the product pointless: you could see a client’s message and would still have to open Gmail to answer it. It is, however, narrower than the full-access scope — it cannot permanently delete mail, so the worst case does not include losing anything irrecoverably.
What encryption actually protects here
Tokens and any OAuth client secret are encrypted with AES-256-GCM before being written. The part worth understanding is what is bound into the encryption: your user id and the purpose of the record are passed as additional authenticated data, which means a row lifted out of the database and inserted under a different account will simply fail to decrypt rather than decrypt into someone else’s mailbox.
The key lives in the server environment, never in the database beside the data it protects, and it is versioned, so it can be rotated without invalidating existing records. Decryption happens only inside server code, only to make a Google API call. Decrypted values are never returned to the browser, and a test asserts it.
What this does not protect against, stated plainly: anyone who controls the running server can read what it decrypts. That is true of every service that acts on your mail on your behalf, and it is the reason the revocation link below matters more than the encryption does.
Staying in control
- Revoke from Postbox. Disconnecting a mailbox calls Google’s revocation endpoint first, then deletes the stored tokens and activity.
- Revoke from Google. You never have to come back here. Remove Postbox at myaccount.google.com/connections and the token stops working immediately.
- Delete everything. One action removes every mailbox, credential, setting, activity row and log. Your Gmail is untouched.
The verification constraint
Because gmail.modify is a restricted scope, Google requires app verification plus a third-party CASA security assessment before a project can serve the general public. Until that is complete, a deployment runs in Google’s Testing mode, where only explicitly listed test users can connect at all and refresh tokens expire every seven days.
This is stated here rather than buried because it is the most likely reason Postbox will not work for you right now, and finding that out after connecting is worse than reading it before.
Common questions
What Gmail permission does Postbox ask for?
One Gmail scope: gmail.modify. It allows reading messages, sending mail, and changing labels — which covers star, archive and mark-as-read. It does not allow permanently deleting mail, and Postbox also requests openid, email and profile purely to identify which Google account you connected.
Why does Postbox need permission to send email?
Because replying is the point. A read-only scope would make Postbox a viewer you still had to leave in order to answer anything, which defeats the reason for putting several mailboxes in one place. gmail.modify is the narrowest single scope that covers reading, replying and archiving together.
Can Postbox delete my email?
Not permanently. The gmail.modify scope cannot permanently delete messages — that requires a broader scope which Postbox does not request. It can archive and move messages to Trash, because those are label changes, and anything in Trash stays recoverable in Gmail for 30 days.
Does Postbox store my Gmail password?
No. Postbox never receives it. Authorisation happens entirely on Google’s consent screen, and what Google returns is a token scoped to specific permissions, which you can revoke at any time without changing your password.
What happens when I disconnect a mailbox?
Postbox calls Google’s revocation endpoint, which invalidates the token at Google, then deletes the stored tokens and that mailbox’s activity rows. The Gmail account itself is untouched — no messages, labels or settings change.
Why does my access keep expiring after seven days?
Because the Google project is unverified. gmail.modify is a restricted scope, so Google requires verification and a third-party CASA security assessment before a project leaves Testing mode. In Testing mode only listed test users can connect and refresh tokens expire every seven days.
Postbox · What is stored· FAQ · Managing multiple Gmail accounts·