Connect a Gmail watch source

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:

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. 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; 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 and all Gmail source types.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Connect a Gmail watch source

Bind a client and verifier

Implement the structural client

Verify push before decoding authority

Cursor recovery and scheduling

​Bind a client and verifier

​Implement the structural client

​Verify push before decoding authority

​Cursor recovery and scheduling

Bind a client and verifier

Implement the structural client

Verify push before decoding authority

Cursor recovery and scheduling