- [HTTP request](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#body.HTTP_TEMPLATE)
- [Path parameters](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#body.PATH_PARAMETERS)
- [Request body](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#body.request_body)
  - [JSON representation](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#body.response_body)
  - [JSON representation](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#body.WatchResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#body.aspect)
- [LabelFilterAction](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction)

Set up or update a push notification watch on the given user mailbox. For more information, see [Configure push notifications in Gmail API](https://developers.google.com/workspace/gmail/api/guides/push).

### HTTP request

`POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) 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 (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction`), "labelFilterBehavior": enum (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#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 (deprecated)` | ``enum (`https://developers.google.com/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. |
| `labelFilterBehavior` | ``enum (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch#LabelFilterAction`)`` Filtering behavior of `labelIds list` specified. This field replaces `labelFilterAction`; if set, `labelFilterAction` is ignored. |
| `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

Push notification watch response.

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

| JSON representation |
|---|
| ``` { "historyId": string, "expiration": string } ``` |

| Fields ||
|---|---|
| `historyId` | `string` The ID of the mailbox's current history record. |
| `expiration` | `string (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. |

### 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](https://developers.google.com/workspace/guides/configure-oauth-consent).

## 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. |