Integration guide

Gmail integration.

OAuth · one filter

Some AI vendors — Cursor, GitHub Copilot, Perplexity, and others — don't expose a billing API. Stax uses Gmail to fill that gap: it creates one filter that forwards billing receipts from a fixed list of vendor addresses to a single Stax-controlled inbound mailbox ([email protected]). Stax never reads anything else in your Gmail account.

Stax does not read your mail. The only Gmail API surface Stax accesses (gmail.settings.basic) allows creating and deleting filters. The two other scopes Stax requests — openid and email — only reveal your primary Google Account email address (used to label which account is connected). None of these scopes grant access to message content, metadata, contacts, labels, or any other part of your mailbox. Parsing happens at Stax's own inbound address — not inside your Gmail account. See the privacy policy → Gmail integration for the full data handling details.

Auth

OAuth 2.0

Google consent screen

Scopes

3 scopes

openid · email · gmail.settings.basic

Gmail changes

1 filter

Created on connect

Mail read

None

Zero mailbox access

How it works

What Stax does, end to end.

Before you connect: add [email protected] as a forwarding address in your own Gmail Settings → Forwarding and POP/IMAP → Add a forwarding address. Gmail will email a confirmation code to that address; clicking the Confirm link puts [email protected] on your account's verified-forwarding-addresses list. Gmail requires this pre-verification before any filter can forward mail to a new destination, and Stax cannot do it for you — the scope Stax requests (gmail.settings.basic) doesn't allow managing forwarding addresses.

At connect time: you click Connect Gmail in Settings → Integrations. You're sent to Google's standard OAuth consent screen, which shows the single scope being requested. After you grant consent, Stax calls Gmail's filter-creation endpoint exactly once to create one filter forwarding the allowlisted senders to [email protected]. The filter is created in milliseconds; you return to your Stax dashboard and the integration is live.

While connected: Stax makes no further calls to Gmail. When a vendor on the allowlist sends you a receipt, Gmail's filter forwards a copy to [email protected]. A Cloudflare Worker receives each forwarded message, reads the X-Forwarded-For header (which Gmail sets to your Gmail address) to map the receipt back to your workspace, parses the vendor and dollar amount from the message, and surfaces the receipt in the Recent forwarded receipts panel on your Stax dashboard. From there you can click Promote on any receipt to turn it into a tracked subscription — pre-filled with the parsed vendor and amount, leaving you to confirm the plan name, seat count, and billing cycle before saving. Stax never authenticates back into your Gmail account to fetch these messages.

At disconnect time: Stax calls Gmail's filter-deletion endpoint to remove the filter, then revokes the OAuth grant via Google's revocation endpoint. Both actions are recorded in your workspace audit log (Settings → Recent activity). Your tracked subscription records are not deleted — those are your data.

The forwarding-address pre-verification is required. If you click Connect Gmail before adding and verifying [email protected] in your Gmail Settings, the filter creation will fail and Stax will show an error telling you to complete that step. The verification email comes from [email protected] and usually arrives within 30 seconds.

Scope

What gmail.settings.basic does and does not grant.

Stax requests three OAuth scopes. Two are identity scopes (openid and email) that only reveal the email address of the Google Account you're connecting. The third is gmail.settings.basic, the narrowest Gmail scope that exposes the filter-creation API.

openid + email: return your primary Google Account email address in the OAuth response, so Stax can display "Connected: [email protected]" and route forwarded receipts to the right workspace. No mailbox access of any kind.
gmail.settings.basic — what it allows: create, list, and delete Gmail filters (users.settings.filters.*). That is the only Gmail API surface Stax uses.
gmail.settings.basic — what it does not allow: reading message content or metadata, listing threads or labels, sending mail, modifying messages, accessing contacts, changing forwarding addresses directly (Gmail's separate verification flow controls that), or any other account action.

Stax does not store the OAuth access token after the single filter-creation call completes; it is held in memory for that one request and then discarded. The encrypted refresh token is stored so the filter can be deleted on disconnect.

Why not a narrower Gmail scope? There isn't one. Gmail's filter-creation endpoint requires gmail.settings.basic, gmail.modify, or full-mailbox access. gmail.settings.basic is the narrowest of those three. Stax does not request gmail.modify or any broader Gmail scope.

Allowlist

Exactly which senders get forwarded.

The Gmail filter's criteria.from matches only the addresses listed below. No other mail is forwarded. The list is static — adding a new vendor requires a code change and re-deploy. Users cannot edit it.

Anthropic

[email protected]

Cursor

GitHub

OpenAI

Perplexity

Stripe (used by several AI vendors for checkout and receipts)

Google (Workspace and Cloud AI invoices)

Note on Stripe: Stripe appears because several AI vendors use Stripe for checkout. The Stax parser ignores Stripe receipts whose product description doesn't match a tracked-vendor pattern — an unrelated Stripe charge will be forwarded but not added to your dashboard.

Forwarded mail

What happens to receipts after they're forwarded.

Forwarded messages land at [email protected] — a single shared inbound terminated by Cloudflare Email Routing. A Cloudflare Worker receives each message and:

Reads the X-Forwarded-For header — Gmail sets this to your Gmail address when its filter forwards a message — and matches it against your connected Gmail integration to resolve the workspace. Messages from a Gmail address with no connected integration are still stored (parse status no_workspace_match) so stray mail is auditable, but they are not surfaced in any user's dashboard.
Parses the receipt using a vendor-specific, deterministic parser — no AI or LLM calls. Today the parser extracts the vendor (from the sender address) and the dollar amount (from the subject line or message body), plus a Message-ID for deduplicating re-forwards.
Inserts a row into your inbound_receipts table and surfaces the receipt in the Recent forwarded receipts panel inside /app. The receipt does not automatically become a tracked subscription — you click Promote on the row to do that, confirming or adjusting the plan name, seat count, and billing cycle.

Stax stores the raw forwarded email content (RFC 822) so parser failures can be reproduced and re-parsed. Parsed subscription records (vendor, amount) and any subscriptions you Promote from them are kept for as long as your workspace exists.

Stax never reads from your Gmail account. The parsing described above happens entirely on Stax's infrastructure, on messages delivered to Stax's own address. Stax does not authenticate back into your Gmail account at any point after the initial filter-creation call.

Disconnect

How to disconnect and what happens when you do.

Go to Settings → Integrations → Gmail → Disconnect and confirm the prompt. Stax then:

Calls users.settings.filters.delete with the stored filter ID. The filter is removed from your Gmail account immediately.
Calls https://oauth2.googleapis.com/revoke with the stored refresh token. The OAuth grant is revoked.
Deletes the encrypted refresh token, the filter ID, and the associated Gmail address from Stax's database.
Logs all three actions to your workspace audit log (visible at Settings → Recent activity).

Your tracked subscription records are not deleted on disconnect. Those rows belong to you and remain in your dashboard. If you want to delete them, use Settings → Privacy → Delete account, or email [email protected].

You can also disconnect at any time directly from your Google account at myaccount.google.com/permissions → Stax. Revoking there has the same effect as disconnecting inside Stax, though Stax won't know to delete the filter from your Gmail automatically — you'd need to remove it manually in Gmail → Settings → Filters and Blocked Addresses.

Frequently asked questions

Can Stax read my email?

No. The scope Stax requests — gmail.settings.basic — does not grant access to message content, metadata, contacts, or labels. Stax's only Gmail-side action is creating (and later deleting) a filter.

Will Stax forward mail I don't expect?

Only mail from the addresses listed in the allowlist above. The filter uses an exact-sender match. Newsletters, personal mail, and anything not from those specific addresses will not be forwarded.

What if the filter is still there after I disconnect?

This shouldn't happen, but if it does: go to Gmail → Settings (gear icon) → See all settings → Filters and Blocked Addresses. Find the filter forwarding to [email protected] and delete it. Email [email protected] and Stax will investigate the disconnect failure.

Does Stax store my emails?

Stax stores the parsed receipt data (vendor, amount) and any subscriptions you promote from a receipt indefinitely while your account exists. The raw forwarded email content is kept so parser failures can be reproduced and re-parsed. Mail that was never forwarded — the vast majority of your inbox — is never seen by Stax at all.

Which accounts can connect Gmail?

Any Stax workspace member can connect Gmail, but they can only connect their own Google account. The integration tracks receipts forwarded from that account. If your team's billing receipts go to a shared inbox or a finance alias, the person who owns that Google account needs to connect.

Ready to pull every billing receipt into one place?

Stax is in private beta. Connect Gmail in two clicks, then watch every AI vendor receipt land in one dashboard alongside your API spend. Join the waitlist to lock in founding-member pricing — $29/mo forever for the first 100 sign-ups.

Join the waitlist →