Technical transparency

Exactly how it works.

This page exists because you should know exactly what happens when you connect your Gmail account to Vail0. No vague reassurances. Here's the technical reality.

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, with no Vail0 server 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, but you will not be able to use the tool.

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. Vail0 itself sets no cookies (Google's sign-in library, and Stripe's checkout if you open it, manage their own). 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 — no message content, subject lines, or sender information is returned. 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 the free clear makes. Two types. Nothing else.

The paid cleanup tools — what they add

The paid tools make more Gmail API calls than the free clear, so here's the same honesty about those. Every one of them still runs in your browser, directly against googleapis.com, with the same memory-only token. All are covered by the same gmail.modify permission — buying access requests nothing new from Google. The one exception to browser-direct is the one-click unsubscribe, which goes through a Vail0 relay — described honestly below.

Counting your newsletters

One search for the last two months of bulk mail — read or unread (Gmail's own ^unsub flag, falling back to the Promotions and Updates categories). Returns message IDs only. This runs only after you tap "check my newsletters".

Building your sender list

For the messages that search found, your browser fetches headers only the sender, mailing-list ID (List-ID), unsubscribe address (List-Unsubscribe), and which of your addresses it was delivered to. format=metadata with named headers: no message bodies, no subject lines. This is how the ranked sender list on your screen gets built, and it exists only on your screen.

Unsubscribing

Where a sender declares one-click unsubscribe (the List-Unsubscribe-Post header — their explicit promise that a single web request is enough), your browser sends that one request through a Vail0 relay — browser security policy won't let a web page call an arbitrary sender's server directly, so your browser hands the relay the sender's own unsubscribe link, plus proof of your license, and nothing else. The relay forwards the request to the sender and reports back whether it worked. We don't store the link, and we log only the sender's domain and the result, briefly. There's no page to visit. Where a sender instead supports email unsubscribe, your browser sends the unsubscribe email from your own account via messages.send — those show up in your Sent folder. An unsubscribe is a request the sender must honor and most stop within days; US law gives them 10 business days, so a straggler or two may still arrive. Because it's your sending quota, we budget it: Gmail allows a finite number of sends per day (about 500 on a personal account, 2,000 on Workspace) and we stop well short of that — and if you have more lists than one day's budget covers, you choose which ones we spend it on, not us. Where a sender only offers a web page, we give you the link and the exact address to type. Unfortunately we can't remove that friction.

Clearing your backlog of emails

Same batchModify call as the free clear — removing the UNREAD label from the messages you chose to clear. Nothing goes to Trash, nothing moves, and nothing is deleted: every message stays exactly where it is, just marked read. Vail0 never deletes mail.

The tools' memory: hidden labels in your own mailbox

So you're never re-offered a list you already unsubscribed from, handled messages get a hidden label (vail0/unsub, vail0/cleared) written into your own Gmail, and mailing lists you've simply been shown are remembered the same way (vail0/seen) — that's how a return visit can point out the lists you passed on last time. The entire memory system lives in your mailbox, not our database. Hidden only means it doesn't clutter your label list: they're your labels, in your account, visible to you in Gmail's settings, and deleting the vail0/ labels erases Vail0's memory completely. We chose this over a server database on purpose: what the tools did for you is recorded somewhere only you control.

The only things that ever touch Vail0's servers

Exactly four kinds of requests can reach Vail0's servers — every one of them optional, and none contains your messages:

  • A license check (paid tools). Your browser sends a Google-signed proof of identity (an ID token — a different credential from the Gmail token, one that grants no mail access at all). We verify it and answer one question: does this account have an active license?
  • A checkout request (buying access). The same identity proof, used to create your Stripe payment page. Stripe handles the card; a Stripe receipt confirmation tells us to record "this account is licensed until this date."
  • A share image. Your browser generates an image containing just your cleared count and uploads it so the link can unfurl. This allows you to show friends and family what this tool did for you and auto-deleted after 90 days.
  • A one-click unsubscribe relay (paid tools). The sender's own unsubscribe link plus proof of your license — the request described under "Unsubscribing" above. We forward it, log the sender's domain and the result briefly, and store nothing.

The Gmail token is never in any of these requests. The two credentials never mix: one proves who you are, the other moves your mail, and only the first ever leaves your browser.

What we never do

  • Call any endpoint that returns message content — bodies stay unread by us in every tier
  • Read subject lines (the paid sender list uses sender/list headers only, and only on your screen)
  • Store message IDs, headers, or anything Gmail-derived after the session ends (sole exception: the one-click relay's brief log of sender domain and result)
  • Send your mail to Vail0's servers — the only mailbox-derived thing that ever reaches us is the sender's unsubscribe link during a one-click unsubscribe, described above
  • Permanently delete mail, ever
  • Make any API call not described on this page

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 available in your browser's developer tools at any time. You can verify everything described on this page directly.

Questions

Anything on this page unclear, or something not working the way it says? Email support@vail0.com — we're a small team but we answer.

Back to the tool