> ## 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.

# Gmail watch source

> Structural Gmail client, source options, and verified push hints.

Structural Gmail client, source options, and verified push hints. Read the [gmail watch source guide](/harness/gmail) for examples, defaults, and behavior.

These declarations cover every public export in this category. Import from `@agentium/harness`. Types such as `ChatMessage`, `RunContext`, and `ExecutionServices` come from [`@agentium/core`](/api-reference/core). A `?` marks an optional field.

## GmailWatchClient

```typescript theme={null}
/** Structural subset of an already-authenticated Gmail client; no SDK or credentials are loaded. */
export interface GmailWatchClient {
    users: {
        getProfile(params: {
            userId: string;
        }, options: RequestOptions): Result<{
            historyId?: string | null;
            emailAddress?: string | null;
        }>;
        watch(params: {
            userId: string;
            requestBody: {
                topicName: string;
                labelIds?: string[];
                labelFilterBehavior?: "INCLUDE";
            };
        }, options: RequestOptions): Result<{
            historyId?: string | null;
            expiration?: string | null;
        }>;
        stop(params: {
            userId: string;
        }, options: RequestOptions): Promise<unknown>;
        history: {
            list(params: {
                userId: string;
                startHistoryId: string;
                historyTypes: string[];
                maxResults: number;
                pageToken?: string;
            }, options: RequestOptions): Result<{
                historyId?: string | null;
                nextPageToken?: string | null;
                history?: Array<{
                    id?: string | null;
                    messagesAdded?: Array<{
                        message?: {
                            id?: string | null;
                            labelIds?: string[] | null;
                        } | null;
                    }>;
                }>;
            }>;
        };
        messages: {
            list(params: {
                userId: string;
                maxResults: number;
                pageToken?: string;
                labelIds?: string[];
            }, options: RequestOptions): Result<{
                messages?: Array<{
                    id?: string | null;
                }>;
                nextPageToken?: string | null;
            }>;
            get(params: {
                userId: string;
                id: string;
                format: "metadata";
                metadataHeaders: string[];
            }, options: RequestOptions): Result<GmailMessage>;
        };
    };
}
```

## GmailWatchOptions

```typescript theme={null}
export interface GmailWatchOptions {
    id: string;
    mailbox: string;
    identity: WatchIdentity;
    topicName: string;
    labelIds?: string[];
    client: GmailWatchClient;
    /** Host verifies Pub/Sub signature, audience and subscription ownership before decoding. */
    verifyPush?: (raw: unknown) => Promise<{
        identity: WatchIdentity;
        messageId: string;
        data: {
            emailAddress: string;
            historyId: string;
        };
    }>;
}
```

## gmailWatchSource

```typescript theme={null}
/** Optional Gmail source: daily renewal/polling are scheduled by DurableWatch, not in this constructor. */
export declare function gmailWatchSource(options: GmailWatchOptions): WatchSource;
```

## Supporting types

These shapes appear in the signatures above but are not named exports of the package entrypoint.

### RequestOptions

```typescript theme={null}
type RequestOptions = {
    signal: AbortSignal;
};
```

### Result

```typescript theme={null}
type Result<T> = Promise<{
    data: T;
}>;
```

### GmailMessage

```typescript theme={null}
interface GmailMessage {
    id?: string | null;
    internalDate?: string | null;
    snippet?: string | null;
    payload?: {
        headers?: Array<{
            name?: string | null;
            value?: string | null;
        }>;
    } | null;
}
```


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