> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a Gmail watch source

> Adapt an authenticated Gmail client to bounded watch reads and verified push hints.

`gmailWatchSource()` adapts an already authenticated structural Gmail client to `WatchSource`. It loads no Google SDK, credentials, or environment configuration and starts no background jobs. `DurableWatch` owns explicit activation, polling, renewal, and digest delivery.

## Bind a client and verifier

This integration factory accepts the host's client and push verifier; it does not subscribe to a mailbox:

```typescript theme={null}
import {
  gmailWatchSource,
  type GmailWatchClient,
  type GmailWatchOptions,
  type WatchIdentity,
} from "@agentium/harness";

export function inboxSource(
  client: GmailWatchClient,
  identity: WatchIdentity,
  mailbox: string,
  topicName: string,
  verifyPush: NonNullable<GmailWatchOptions["verifyPush"]>,
) {
  return gmailWatchSource({
    id: "gmail-inbox",
    client,
    identity,
    mailbox,
    topicName,
    labelIds: ["INBOX"],
    verifyPush,
  });
}
```

Use the returned `source.id` and `source.scope` in the [watch definition](/harness/watches). Pass the source as `WatchServices.source`, then explicitly activate the watch when the host authorizes it.

| Option | Contract |
| - | - |
| `id` | Source identifier used by the watch definition. |
| `mailbox` | Mailbox identity checked against authenticated profile and push data. |
| `identity` | Verified `{ tenantId, actorId }` expected on push hints. |
| `topicName` | Host-provisioned Pub/Sub topic name sent to the Gmail watch request. |
| `labelIds` | Optional Gmail label filter. |
| `client` | Structural `GmailWatchClient`; your host owns authentication and its lifetime. |
| `verifyPush` | Optional trusted verifier. Required for using push triggers; polling does not require it. |

## Implement the structural client

The client exposes `users.getProfile`, `users.watch`, `users.stop`, `users.history.list`, `users.messages.list`, and `users.messages.get`. Requests receive abort signals. Methods return the `{ data }` shapes in the [Gmail reference](/harness/api/gmail#gmailwatchclient); no particular SDK dependency is imposed.

The adapter requests message metadata with From, To, Subject, and Date headers plus the returned snippet. It does not fetch complete message bodies. Source content remains untrusted data; classification belongs in a deterministic watch filter.

## Verify push before decoding authority

The host verifier must authenticate the push signature, audience, subscription ownership, and mailbox/principal binding. It returns `{ identity, messageId, data: { emailAddress, historyId } }`. The adapter validates the returned scope before producing a verified trigger.

Do not use an unverified HTTP body as that return value. Grant references and mailbox strings cannot establish authority. Enforce exclusive ownership of the active mailbox/configuration in the host so competing versions cannot replace one another's subscription.

Pass incoming requests to `watch.trigger(raw)` and acknowledge only after it resolves. A verified hint can wake the watch, but cannot advance the stored cursor on its own.

## Cursor recovery and scheduling

Gmail history IDs remain decimal strings and are compared using `BigInt`, avoiding numeric precision loss. Incremental reads and full-sync fallback honor watch page and event bounds. An expired-history 404 triggers a bounded full sync; its historical entries become suppressed decisions and do not generate historical notifications.

The watch schedules renewal using the configured interval and subscription expiry, and polls as a fallback to push. Your scheduler must persist and dispatch those jobs. A structural client fixture verifies your adapter contract, but does not verify live OAuth, push infrastructure, or a notification provider's reconciliation behavior.

See [watch lifecycle and limits](/harness/watches) and [all Gmail source types](/harness/api/gmail).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.