Method: users.watch
Stay organized with collections
Save and categorize content based on your preferences.
Set up or update a push notification watch on the given user mailbox.
HTTP request
POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch
The URL uses gRPC Transcoding syntax.
Path parameters
| Parameters |
userId |
string
The user's email address. The special value me can be used to indicate the authenticated user.
|
Request body
The request body contains data with the following structure:
| Fields |
labelIds[] |
string
List of labelIds to restrict notifications about. By default, if unspecified, all changes are pushed out. If specified then dictates which labels are required for a push notification to be generated.
|
labelFilterAction
(deprecated) |
enum (LabelFilterAction)
Filtering behavior of labelIds list specified. This field is deprecated because it caused incorrect behavior in some cases; use labelFilterBehavior instead.
|
labelFilterBehavior |
enum (LabelFilterAction)
Filtering behavior of labelIds list specified. This field replaces labelFilterAction; if set, labelFilterAction is ignored.
|
topicName |
string
A fully qualified Google Cloud Pub/Sub API topic name to publish the events to. This topic name must already exist in Cloud Pub/Sub and you must have already granted gmail "publish" permission on it. For example, "projects/my-project-identifier/topics/my-topic-name" (using the Cloud Pub/Sub "v1" topic naming format). Note that the "my-project-identifier" portion must exactly match your Google developer project id (the one executing this watch request).
|
Response body
Push notification watch response.
If successful, the response body contains data with the following structure:
| JSON representation |
{
"historyId": string,
"expiration": string
} |
| Fields |
historyId |
string
The ID of the mailbox's current history record.
|
expiration |
string (int64 format)
When Gmail will stop sending notifications for mailbox updates (epoch millis). Call watch again before this time to renew the watch.
|
Authorization scopes
Requires one of the following OAuth scopes:
https://mail.google.com/
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.metadata
For more information, see the Authorization guide.
LabelFilterAction
Filtering behavior of labelIds list specified.
| Enums |
include |
Only get push notifications for message changes relating to labelIds specified. |
exclude |
Get push notifications for all message changes except those relating to labelIds specified. |
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-03-24 UTC.
[null,null,["Last updated 2025-03-24 UTC."],[],[],null,["# Method: users.watch\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Request body](#body.request_body)\n - [JSON representation](#body.request_body.SCHEMA_REPRESENTATION)\n- [Response body](#body.response_body)\n - [JSON representation](#body.WatchResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [LabelFilterAction](#LabelFilterAction)\n\nSet up or update a push notification watch on the given user mailbox.\n\n### HTTP request\n\n`POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n| Parameters ||\n|----------|-----------------------------------------------------------------------------------------------------------|\n| `userId` | `string` The user's email address. The special value `me` can be used to indicate the authenticated user. |\n\n### Request body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"labelIds\": [ string ], \"labelFilterAction\": enum (/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction), \"labelFilterBehavior\": enum (/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction), \"topicName\": string } ``` |\n\n| Fields ||\n|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `labelIds[]` | `string` List of labelIds to restrict notifications about. By default, if unspecified, all changes are pushed out. If specified then dictates which labels are required for a push notification to be generated. |\n| `labelFilterAction` **(deprecated)** | `enum (`[LabelFilterAction](/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction)`)` Filtering behavior of `labelIds list` specified. This field is deprecated because it caused incorrect behavior in some cases; use `labelFilterBehavior` instead. |\n| `labelFilterBehavior` | `enum (`[LabelFilterAction](/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction)`)` Filtering behavior of `labelIds list` specified. This field replaces `labelFilterAction`; if set, `labelFilterAction` is ignored. |\n| `topicName` | `string` A fully qualified Google Cloud Pub/Sub API topic name to publish the events to. This topic name **must** already exist in Cloud Pub/Sub and you **must** have already granted gmail \"publish\" permission on it. For example, \"projects/my-project-identifier/topics/my-topic-name\" (using the Cloud Pub/Sub \"v1\" topic naming format). Note that the \"my-project-identifier\" portion must exactly match your Google developer project id (the one executing this watch request). |\n\n### Response body\n\nPush notification watch response.\n\nIf successful, the response body contains data with the following structure:\n\n| JSON representation |\n|-------------------------------------------------------|\n| ``` { \"historyId\": string, \"expiration\": string } ``` |\n\n| Fields ||\n|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `historyId` | `string` The ID of the mailbox's current history record. |\n| `expiration` | `string (`[int64](https://developers.google.com/discovery/v1/type-format)` format)` When Gmail will stop sending notifications for mailbox updates (epoch millis). Call `watch` again before this time to renew the watch. |\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://mail.google.com/`\n- `\n https://www.googleapis.com/auth/gmail.modify`\n- `\n https://www.googleapis.com/auth/gmail.readonly`\n- `\n https://www.googleapis.com/auth/gmail.metadata`\n\nFor more information, see the [Authorization guide](/workspace/guides/configure-oauth-consent).\n\nLabelFilterAction\n-----------------\n\nFiltering behavior of labelIds list specified.\n\n| Enums ||\n|-----------|---------------------------------------------------------------------------------------------|\n| `include` | Only get push notifications for message changes relating to labelIds specified. |\n| `exclude` | Get push notifications for all message changes except those relating to labelIds specified. |"]]
