Es una lista de labelIds para restringir las notificaciones. De forma predeterminada, si no se especifica, se envían todos los cambios. Si se especifica, indica qué etiquetas son necesarias para que se genere una notificación push.
Se especificó el comportamiento de filtrado de labelIds list. Este campo dejó de estar disponible porque causaba un comportamiento incorrecto en algunos casos. En su lugar, usa labelFilterBehavior.
Se especificó el comportamiento de filtrado de labelIds list. Este campo reemplaza a labelFilterAction. Si se establece, se ignora labelFilterAction.
topicName
string
Es un nombre de tema de la API de Google Cloud Pub/Sub completamente calificado en el que se publicarán los eventos. Este nombre de tema debe existir ya en Cloud Pub/Sub y debes haberle otorgado a Gmail el permiso de "publicación". Por ejemplo, "projects/my-project-identifier/topics/my-topic-name" (con el formato de nombres de temas "v1" de Cloud Pub/Sub).
Ten en cuenta que la parte "my-project-identifier" debe coincidir exactamente con el ID de tu proyecto de desarrollador de Google (el que ejecuta esta solicitud de reloj).
Cuerpo de la respuesta
Respuesta del reloj a la notificación push.
Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:
Representación JSON
{"historyId": string,"expiration": string}
Campos
historyId
string
Es el ID del registro de historial actual del buzón de correo.
Indica cuándo Gmail dejará de enviar notificaciones de actualizaciones de buzón (milésimas de época). Vuelve a llamar a watch antes de este tiempo para renovar el reloj.
Permisos de autorización
Se necesita uno de los siguientes permisos de OAuth:
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Falta la información que necesito","missingTheInformationINeed","thumb-down"],["Muy complicado o demasiados pasos","tooComplicatedTooManySteps","thumb-down"],["Desactualizado","outOfDate","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Problema con las muestras o los códigos","samplesCodeIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-07-25 (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. |"]]
