Gmail API Push Notifications

• Gmail API offers server push notifications for tracking changes in Gmail mailboxes.
• This feature enhances application performance by removing the need to constantly poll resources for updates.
• Instead of polling, the Gmail API sends a notification to the backend server when a mailbox is altered.
• Poll-based sync is still the recommended option for notifications to user-owned devices

Initial Cloud Pub/Sub Setup

• Gmail API uses the Cloud Pub/Sub API to send push notifications.
• Notifications are delivered through methods like webhooks and subscription endpoint polling.
• Cloud Pub/Sub Prerequisites must be fulfilled before the setup.
• Set up a Cloud Pub/Sub client

Creating a Topic

• Using the Cloud Pub/Sub client, create a topic where the Gmail API will send notifications.
• The topic name should match projects/myproject/topics/* where myproject is the Project ID in the Google Developers Console.

Creating a Subscription

• Set up a subscription to the topic, using the Cloud Pub/Sub Subscriber Guide.
• Subscription type can be a webhook push/HTTP POST callback or pull/initiated by the app.
• This setup enables the application to receive update notifications.

Granting Publish Rights

• Grant Gmail permission to publish notifications to the designated topic.
• Provide publish privileges to gmail-api-push@system.gserviceaccount.com.
• This can be done through the Cloud Pub/Sub Developer Console permissions interface.

Getting Gmail Mailbox Updates

• Configure Gmail accounts to send notifications for mailbox updates after completing the Cloud Pub/Sub setup.
• Use the Gmail API client to call watch on the Gmail user mailbox.
• Provide the created topic name and any other options, like filtering with labels, in the watch request.

Watch Request Example

• To receive notifications for any changes made to the Inbox:
• Specify INBOX in the labelIds array and set the labelFilterBehavior to INCLUDE in the watch request.
• Provide topic name
• Make a post request

Watch Response

• A successful watch request returns the current mailbox historyId and an expiration timestamp.
• Changes after the historyId are notified to the client.
• The sync guide can be used to process changes prior to this historyId.
• A successful watch call will immediately send a notification to the Cloud Pub/Sub topic.

Handling Errors

• If the watch call returns an error, the details indicate the problem source, typically related to the Cloud Pub/Sub topic and subscription setup.
• Refer to Cloud Pub/Sub documentation to verify the setup and for debugging assistance.

Renewing Mailbox Watch

• The watch must be re-called at least every 7 days to continue receiving updates; daily re-calling is recommended.
• The watch response includes an expiration field that shows the timestamp for when the watch will expire.

Receiving Notifications

• The application will receive a notification message that describes the change when a mailbox update matches the watch.
• For push subscriptions, the webhook notification to the server will take the form of a PubsubMessage.
• The Gmail notification payload is in the message.data field, a base64url-encoded string that decodes to a JSON object.
• JSON object contains the email address and the new mailbox history ID for the user.

Processing Notifications

• Use history.list to get the change details for the user since the last known historyId.
• Persist the new historyId for future use.
• For pull subscription refer to the code samples in the Cloud Pub/Sub Subscriber Pull Guide to get further details on receiving messages.

Responding to Notifications

• Notifications need to be acknowledged.
• For webhook push delivery, a successful HTTP 200 response acknowledges the notification.
• For pull delivery, follow up with an acknowledge call
• If notifications are not acknowledged Cloud Pub/Sub will retry the notification at a later time.

Stopping Mailbox Updates

• To stop receiving updates, call stop.
• All new notifications should cease within minutes.

Limitations

• Each Gmail user has a maximum notification rate of 1 event/second.
• Notifications exceeding this rate will be dropped.
• Be careful not to trigger more notifications to avoid a loop.
• Applications should handle potential delays or dropped notifications, possibly by periodically calling history.list.

Cloud Pub/Sub Limitations

• The Cloud Pub/Sub API has its own limitations.
• Refer to its pricing and quotas documentation.