Skip to main content
This guide builds a push trigger that runs a task for each new email in a requester’s Gmail inbox. Gmail announces changes to a Pub/Sub topic, Pub/Sub delivers them to your server, and your server dispatches them to the schedules watching that mailbox. In Slack, installing the app is the subscription. A Gmail watch, by contrast, lapses after 7 days, so the trigger renews the watch daily while its schedule is active.
Gmail’s read scopes are restricted. To publish an app that uses them, you need Google’s verification, which includes a security assessment. While the app is in testing, only the test users you add can connect.
1

Set up Google Cloud

In a Google Cloud project:
  1. Enable the Gmail API and the Pub/Sub API.
  2. Create an OAuth client for a web application, with your redirect URI, such as https://inbox.example.com/oauth/callback.
  3. Create a Pub/Sub topic, such as projects/acme/topics/gmail, and grant gmail-api-push@system.gserviceaccount.com the Pub/Sub Publisher role on it.
  4. Create a push subscription on the topic that delivers to your server, such as https://inbox.example.com/gmail/push, with authentication turned on so you can verify each delivery.
Then set the OAuth client’s settings as environment variables for your agent:
2

Install the Gmail client

3

Declare the Google connection

The skill reads each requester’s inbox through a Google connection with a Gmail read scope. googleConnection() (google_connection() in Python) reads the OAuth client’s settings from the environment, and keeps tokens in a token store, which here is store:
4

Write the trigger

The hook starts a watch on the schedule’s mailbox and renews the watch daily. It also subscribes the schedule to an event key built from the mailbox’s address, since Pub/Sub’s notifications include that address. The stop function that the hook returns ends the renewals:
Each renewal asks for a fresh token, since access tokens expire well before a day passes. historyIds is a small table in your database that stores the last history id read for each mailbox, so each run knows where to start reading. The hook may run more than once for the same schedule, as described in When the hook runs, so it only sets a history id when one is missing.A watch that’s no longer renewed lapses on its own within 7 days, so stop doesn’t need to end it. Calling Gmail’s users.stop would also end the watch for every other schedule on the same mailbox.
5

Add the connection and trigger to a skill

6

Read the new emails

Each run reads the mailbox’s history since the last saved history id, then saves the new one:
The Python client’s calls are synchronous. In an agent that handles many tasks at once, run them with asyncio.to_thread() so they don’t block other tasks.
7

Serve Pub/Sub and OAuth callbacks

Your server answers two kinds of requests:
  • Pub/Sub deliveries, which carry the mailbox’s emailAddress and latest historyId, encoded in base64. Verify the delivery’s token, then dispatch an event with the mailbox’s key. Because of the event id, a notification that Pub/Sub delivers again still starts only one run per schedule.
  • OAuth callbacks at the redirect URI, once a human connects their Google account. Pass each one to receiveOAuth() (receive_oauth() in Python), which stores the account’s tokens and returns a page for the human.
verifyPubSubToken uses a Google auth library to check the OIDC token that Pub/Sub sends. If dispatching throws, your server responds with an error, which makes Pub/Sub retry the delivery.
Requesters then schedule the trigger by its name, new_email. Each requester’s human connects Google through the OAuth link, and from then on each new email starts a run.