Gmail PubSub Integration

+15 Mana ✨
OpenClaw Gmail Integration(DOCUMENTATION)Gmail API Push Notifications(DOCUMENTATION)

Introduction

OpenClaw includes a built-in Gmail PubSub integration that lets your agent monitor email inboxes and react to incoming messages. This is powered by Google Cloud Pub/Sub, which pushes email notifications to your Gateway in real time. This lesson covers the setup, configuration, and practical usage of Gmail monitoring.

Key Concepts

  • Gmail PubSub: Google's push notification system for Gmail that delivers email events to registered endpoints
  • openclaw webhooks gmail setup: The CLI command that configures the Gmail watch and Pub/Sub subscription
  • openclaw webhooks gmail run: Starts the Gmail webhook listener that processes incoming email notifications
  • Email Monitoring: Watching for specific emails based on labels, senders, or subjects
  • Email Summarization: Using the agent to extract key information from incoming emails

Real World Context

A project manager receives dozens of emails daily from clients, vendors, and internal teams. They configure an OpenClaw agent to monitor their inbox, summarize important emails, and flag any messages that require urgent action. The agent sends a digest to their Telegram chat every time a high-priority email arrives, letting them triage without opening their email client.

Deep Dive

Setting Up Gmail PubSub

The setup command configures the Google Cloud Pub/Sub subscription and Gmail API watch:

bash
openclaw webhooks gmail setup \
  --project-id "my-gcp-project" \
  --credentials "./service-account.json"

This command authenticates with Google Cloud using the provided service account credentials, creates a Pub/Sub topic and subscription if they do not exist, and registers a Gmail API watch on the authenticated user's inbox. The setup only needs to be done once.

Running the Gmail Listener

Once setup is complete, start the listener to begin processing email events:

bash
openclaw webhooks gmail run

This starts a long-running process that listens for Pub/Sub notifications from Gmail. When a new email arrives, the notification is converted into an event and delivered to the configured agent. The agent then processes the email content and takes appropriate action.

Email Processing Configuration

You can configure which emails the agent should process and how:

json
{
  "webhooks": {
    "gmail": {
      "labels": ["INBOX", "IMPORTANT"],
      "actions": {
        "summarize": true,
        "notify": {
          "channel": "telegram",
          "onlyIfUrgent": true
        }
      }
    }
  }
}

This configuration tells the agent to monitor emails with the INBOX or IMPORTANT labels, summarize each one, and send a notification to Telegram only if the email is classified as urgent.

Practical Example: Daily Email Digest

Combine Gmail PubSub with a cron job for a daily digest pattern:

bash
# Gmail webhook processes emails in real time
openclaw webhooks gmail run

# Cron job sends a daily summary at 6 PM
openclaw cron add \
  --cron "0 18 * * 1-5" \
  --message "Compile today's email summary and send to Slack"

The Gmail webhook captures and processes emails throughout the day. The cron job then generates a consolidated summary at the end of each business day.

Common Pitfalls

  • Not refreshing the Gmail watch: Gmail API watches expire after 7 days. You must set up a cron job or renewal mechanism to call gmail setup periodically.
  • Missing Google Cloud IAM permissions: The service account needs both Pub/Sub and Gmail API permissions. Missing either will cause silent failures.
  • Processing all emails indiscriminately: Without label or sender filters, the agent will process every email including spam and notifications, wasting tokens.

Best Practices

  • Set up a cron job to renew the Gmail watch every 5 days to avoid expiration.
  • Filter emails by labels to reduce unnecessary processing and token costs.
  • Store the service account credentials securely using environment variables or a secrets manager.

Summary

  • Gmail PubSub delivers real-time email notifications to your OpenClaw agent via Google Cloud Pub/Sub
  • openclaw webhooks gmail setup configures the Pub/Sub subscription and Gmail API watch
  • openclaw webhooks gmail run starts the listener that processes incoming email events
  • Filter emails by labels and configure notification rules to reduce noise
  • Gmail watches expire after 7 days and must be renewed periodically
✓ Completed