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 |
The user's email address. The special value |
Request body
The request body contains data with the following structure:
JSON representation |
---|
{ "labelIds": [ string ], "labelFilterAction": enum ( |
Fields | |
---|---|
labelIds[] |
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 |
Filtering behavior of |
labelFilterBehavior |
Filtering behavior of |
topicName |
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 |
The ID of the mailbox's current history record. |
expiration |
When Gmail will stop sending notifications for mailbox updates (epoch millis). Call |
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. |