Users: watch

Requires authorization

Set up or update a push notification watch on the given user mailbox. Try it now.


HTTP request



Parameter name Value Description
Path parameters
userId string The user's email address. The special value me can be used to indicate the authenticated user.


This request requires authorization with at least one of the following scopes (read more about authentication and authorization).


Request body

In the request body, supply data with the following structure:

  "labelIds": [
  "labelFilterAction": string,
  "topicName": string
Property name Value Description Notes
labelIds[] list List of label_ids 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 string Filtering behavior of labelIds list specified.

Acceptable values are:
  • "exclude"
  • "include"
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).


If successful, this method returns a response body with the following structure:

  "historyId": unsigned long,
  "expiration": long
Property name Value Description Notes
historyId unsigned long The ID of the mailbox's current history record.
expiration long When Gmail will stop sending notifications for mailbox updates (epoch millis). Call watch again before this time to renew the watch.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.