Users: watch

Requires authorization

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

Request

HTTP request

POST https://www.googleapis.com/gmail/v1/users/userId/watch

Parameters

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.

Authorization

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

Scope
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

Request body

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

{
  "labelIds": [
    string
  ],
  "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).

Response

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.