Users: watch

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


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:


For more information, see the authentication and authorization page.

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.