Skip to content
ServiceOps

Gmail setup

ServiceOps connects to Gmail through your own Google Cloud OAuth client and your own Cloud Pub/Sub topic — never a ServiceOps-wide project.

1. Enable the Gmail API

Section titled “1. Enable the Gmail API”
  1. Open the Google Cloud Console and create (or pick) a project for this integration.
  2. APIs & Services → Library → search Gmail API → enable it.
Section titled “2. Configure the OAuth consent screen”

APIs & Services → OAuth consent screen. For a Google Workspace organization, the Internal user type is simplest; otherwise External with the mailbox’s account added as a test user is enough.

3. Create an OAuth client

Section titled “3. Create an OAuth client”
  1. APIs & Services → Credentials → Create credentials → OAuth client ID, type Web application.
  2. Under Authorized redirect URIs, paste the callback URL shown by the ServiceOps wizard: 
    https://YOUR_SERVICEOPS_DOMAIN/api/email-channels/oauth/gmail/callback
  3. Copy the Client ID and Client secret.

4. Create the Pub/Sub topic

Section titled “4. Create the Pub/Sub topic”

Gmail delivers new-mail notifications through Cloud Pub/Sub — this is Google’s own documented mechanism.

  1. Pub/Sub → Topics → Create topic. Note its full name: projects/YOUR_PROJECT/topics/YOUR_TOPIC.
  2. On the topic’s Permissions tab, add the principal gmail-api-push@system.gserviceaccount.com with the role Pub/Sub Publisher. This is Google’s fixed service account for Gmail push — the same for every project, per the official documentation.

5. Connect in ServiceOps

Section titled “5. Connect in ServiceOps”
  1. In Settings → Email channels, choose Gmail.
  2. Enter the Client ID, Client secret, the Gmail address, and the full topic name.
  3. Create the channel, then choose Connect my Google account — sign in, consent, return.

Result: the channel shows Connected; ServiceOps watches the mailbox through Gmail’s push notifications.

How it stays connected

Section titled “How it stays connected”
  • A Gmail watch expires within 7 days; ServiceOps re-watches daily.
  • Google does not rotate refresh tokens on every use; ServiceOps only stores a new one when Google actually returns one — a valid token is never overwritten with nothing.
  • Push notifications carry only a history marker; ServiceOps resolves it to the concrete new messages, and re-baselines automatically if the marker has aged out.
  • If consent is revoked, the channel shows Authentication error — reconnect with the same button.

Official Google references

Section titled “Official Google references”