Exactly how it works.

Step one — you sign in with Google

When you click Connect, a Google sign-in popup opens directly from Google's authentication servers at accounts.google.com. Vail0 never sees your Google password. Ever.

The sign-in uses Google Identity Services (GIS), Google's official library for browser-based OAuth. The access token is returned directly from Google's servers to your browser — no Vail0 server is involved in the exchange. There is no authorization code step and no client secret.

Step two — you grant permission

Google shows you a consent screen listing exactly what Vail0 is requesting access to. You'll see one permission: the ability to read and modify your Gmail messages and labels. This is Google's gmail.modify scope.

You can deny this at any time by clicking cancel. Nothing happens to your account if you do.

Note on scope breadth: gmail.modify technically grants broader access than we use. It could allow reading message content and metadata. We don't use or even want that access, but there wasn't another way to do it. The API calls below are the complete list of what Vail0 actually does.

Step three — Google issues a token

If you approve, Google generates an access token that acts like a key. This token is handed to your browser, not to Vail0's servers.

It lives in your browser's memory only and we don't use cookies. It is never stored in localStorage or sessionStorage. It is never logged anywhere and expires after one hour. It can only be used for the specific actions you approved.

Step four — your browser calls Gmail directly

When you click Clear, your browser uses that token to make API calls directly to Gmail's servers at googleapis.com. Vail0's servers are not involved. The conversation is entirely between your browser and Google.

Here is exactly what those calls do:

Call type 1 — fetch unread message IDs

Two parallel list calls are made. The first fetches your inbox unread count (what your Gmail badge shows):

GET https://gmail.googleapis.com/gmail/v1/users/me/messages?labelIds=INBOX&labelIds=UNREAD&maxResults=500
Authorization: Bearer {token}

The second fetches all unread IDs across every category (what actually gets cleared):

GET https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is%3Aunread&maxResults=500
Authorization: Bearer {token}

Both return IDs only — not message content, not subject lines, and not sender information. Just a list of random string identifiers like 18f2a3b4c5d6e7f8.

If you have more than 500 unread messages, Gmail returns a nextPageToken in the response. We repeat the call with that token until there is no nextPageToken — meaning we've collected all IDs. This is standard API pagination.

Call type 2 — remove the UNREAD label

POST https://gmail.googleapis.com/gmail/v1/users/me/messages/batchModify
Authorization: Bearer {token}
Content-Type: application/json

{
  "ids": ["18f2a3b4c5d6e7f8", "18f2a3b4c5d6e7f9", ...up to 1000],
  "removeLabelIds": ["UNREAD"]
}

This sends up to 1,000 message IDs at a time with one instruction: remove the label called UNREAD. Gmail returns HTTP 204 — success, no content. We repeat until every message ID has been processed.

That's the complete list of API calls Vail0 makes. Two types. Nothing else.

What we never do

• Call any endpoint that returns message content
• Call any endpoint that returns subject lines or sender information
• Store message IDs after the session ends
• Transmit anything to Vail0's servers during the clear process
• Make any API call other than the two described above

Step five — the token expires

When you close the tab the token is gone from memory. After one hour, Google invalidates it regardless. At that point Vail0 has no access to your Gmail account whatsoever. There is nothing stored, no session, and nothing to revoke (other than the app permissions themselves, which you control).

Revoking access

myaccount.google.com/permissions — find Vail0, click Remove Access. Done immediately.

The source code

The JavaScript that runs Vail0 including the OAuth flow and every API call is unminified and readable in your browser's developer tools at any time. Open DevTools → Sources → js/main.js. You can verify everything described on this page directly.

Questions

hello@vail0.com