Method: users.watch

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:

JSON representation 
{
  "labelIds": [
    string
  ],
  "labelFilterAction": enum (LabelFilterAction),
  "topicName": string
}
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

enum (LabelFilterAction)

Filtering behavior of labelIds list specified.
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

If successful, the response body contains data with the following structure:

Push notification watch response.

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.