Gmail as a First-Class Mailbox Provider

Gmail is not just another SMTP mailbox.

That sounds obvious, but it is a decision many email products avoid for too long. They try to force Gmail into the same shape as custom-domain mail, then spend the rest of the product’s life fighting provider-specific behavior.

Banger takes the opposite approach: Gmail is a first-class provider.

That means Gmail has its own OAuth, ingest, backfill, and send paths. Once messages enter Banger’s mailbox model, they participate in the same workspace, workflow, sync, search, and agent systems as every other mailbox. But the provider edge is allowed to be provider-specific.

That separation is what makes the integration stable.

Provider mailboxes are still Banger mailboxes

In Banger, a Gmail account becomes a provider mailbox.

That mailbox has a provider identity and Gmail-specific connection state, but it still behaves like a Banger mailbox in the product:

• it belongs to a workspace
• it can appear next to custom-domain mailboxes
• it participates in shared inbox workflows
• it can be searched
• it can be assigned
• it can be categorized
• it can be used by humans and permitted agents

The user should not need to care that one mailbox is Gmail-backed and another came from custom-domain routing when they are triaging work.

The infrastructure does need to care.

OAuth is the start of provider state

Gmail access begins with OAuth. That gives Banger a provider connection, not just a password-like credential.

The connection has lifecycle and health. It can be valid, expired, revoked, or waiting for setup. It needs history cursors, watch state, backfill state, and validation timestamps. It also needs to be tied to the right workspace and mailbox.

Treating this as provider state keeps the rest of the system cleaner. The mailbox model can ask for provider mail, but it does not need to pretend Gmail auth is the same as SMTP auth.

Incremental ingest uses Gmail watch and Pub/Sub

For new mail, Banger uses Gmail’s watch and Pub/Sub flow.

At a high level:

1. Banger sets up or refreshes a Gmail watch for the account.
2. Gmail publishes notifications to a Pub/Sub topic.
3. Pub/Sub pushes to Banger’s provider endpoint.
4. Banger validates the notification and processes Gmail history.
5. New encrypted ingest metadata is queued for client processing.

This is different from receiving SMTP directly. There is no smtp-input path for provider mailboxes. Gmail owns the provider event, and Banger normalizes the result into its mailbox ingest system.

That keeps provider behavior explicit instead of hidden behind a fake SMTP abstraction.

Outbound mail uses Gmail too

Sending is also provider-specific.

For a custom-domain mailbox, outbound mail can use Banger’s SMTP send infrastructure. For a Gmail provider mailbox, outbound sends should go through the Gmail API.

That matters for deliverability, account behavior, sent-mail consistency, and user expectations. If the user connects Gmail, they expect sent messages to behave like Gmail messages.

So Banger rejects SMTP send paths for provider mailboxes and uses the provider send path instead.

The product-level action is still “send this reply.” The provider implementation is different.

Backfill is client-driven

Historical import is not the same as incremental ingest.

Backfill can involve many messages, many pages of provider history, and long-running state. Banger’s Gmail backfill is client-driven: the client reads Gmail history, uploads encrypted raw content and parts, and writes backfill actions directly into the mailbox stream.

That gives the local runtime more control over pacing, resume behavior, and local resource decisions.

It also keeps backfill separated from normal new-mail ingest. A large history import should not block fresh customer mail from arriving.

Why backfill has its own cursor

Backfill needs resume state:

• last message ID
• last internal date
• last history ID
• page token
• next page token
• query

That state belongs to the history import process. It should not be mixed with the normal action cursor or the incremental ingest cursor.

Separate cursors make recovery much clearer. If backfill stops halfway through a mailbox, it can resume without pretending the entire mailbox sync system is in one global position.

Encryption stays in the mailbox model

Provider-specific ingest does not mean provider-specific trust.

Gmail messages are stored with raw bodies and attachments in mailbox storage, while metadata and actions move through Banger’s encrypted mailbox streams for client processing. The provider integration gets data into the system. The mailbox model controls how that data becomes local product state.

That division keeps Gmail integration from becoming a special product fork.

Gmail cannot own the workflow

Gmail has labels, read state, threads, history, and its own product semantics. Banger has workspace ownership, shared workflows, agent permissions, approvals, categories, and team assignment.

The integration has to respect both sides.

Banger should ingest enough Gmail state to represent the conversation accurately, but the team workflow lives in Banger. A thread can be assigned, categorized, moved into review, proposed by an agent, or resolved in a way that is meaningful to the workspace even if Gmail has no equivalent concept.

That is why provider normalization matters.

A first-class provider is not a shortcut

The easy version of Gmail support is a button that says “Connect Gmail” and a list of messages.

The hard version is making Gmail work inside the same operational model as the rest of the product:

• provider-aware auth
• provider-aware ingest
• provider-aware send
• client-driven encrypted backfill
• separate cursors
• local sync projection
• workspace permissions
• team workflow
• agent-safe operations

That is the version Banger needs.

Gmail is too important to treat as a generic mailbox. It deserves its own provider path. The product becomes simpler because the integration layer is honest about the complexity.