A Gmail API watch expires. Receiving notifications yesterday does not establish that the subscription is still current today. Check the mailbox watch, Cloud Pub/Sub delivery, and the application’s synchronization cursor as separate parts of the pipeline.
Inspect the watch response and renewal job
A successful watch returns a mailbox history ID and an expiration timestamp in epoch milliseconds. Store and monitor that expiration. Google’s guide requires renewal at least every seven days and recommends calling watch daily.
Verify that renewal actually succeeded for the intended mailbox. A scheduled job existing in configuration is not proof it ran, and refreshing an OAuth token does not renew the mailbox watch.
Check Pub/Sub delivery separately
Confirm the expected topic, subscription, and Gmail publisher permission. A watch call should generate an initial notification. For push delivery, inspect the endpoint’s authenticated delivery and successful acknowledgment; unacknowledged notifications can be retried.
The Pub/Sub message ID is not a Gmail message ID. Decode the notification’s data and use its mailbox history ID with the appropriate Gmail history workflow. Do not treat the notification payload as the full content of a new email.
Recover missed changes safely
Notifications can be delayed or dropped, and the guide documents a per-user notification-rate limit. Maintain a synchronization fallback rather than assuming one notification arrives for every mailbox event.
Use the last successfully processed history cursor to retrieve changes and advance it only after durable processing. If the history cursor is no longer available and Gmail returns the documented 404, perform an appropriate full synchronization. Deduplicate downstream actions so redelivery does not send the same reply twice. Retain only the message information needed for the application’s purpose, and never log tokens while diagnosing a stopped watch.
Browse Gmail & Google Account help
References
- Configure push notifications with the Gmail API | Google for Developers
- Synchronize clients with Gmail | Google for Developers
Reviewed against the linked official product guidance on November 3, 2026. Features, limits, screen labels, and access can vary by account, platform, region, and organization policy.