Skip to main content
This guide shows how to:
  • Connect to the Gmail API to retrieve incoming messages
  • Use agents to generate draft replies

Setup Requirements

Install the required Google API client libraries:
1

Create a Google Cloud Project

Go to the Google Cloud Console and create a new project or select an existing one.
2

Enable Gmail API

  1. Navigate to APIs & Services > Library
  2. Search for “Gmail API”
  3. Click on Gmail API and then Enable
3

Choose Authentication Method

There are two ways to authenticate with Gmail API. Choose the one that fits your use case:

Method 1: OAuth 2.0 (Personal/Desktop Apps)

Use this if:
  • You’re building a personal application
  • You want users to authenticate with their own Google account
  • You’re using a personal Gmail account (not Google Workspace)

Setup Steps:

1. Create OAuth 2.0 Credentials
  1. Go to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Choose Desktop app as the application type
  4. Download the credentials JSON file and save it as credentials.json
2. Configure OAuth Scopes The following scopes are required:
3. Generate Access Token Run this script once to generate token.json:
This will open a browser window for Google sign-in.4. Initialize in Code

Method 2: Service Account (Google Workspace)

Use this if:
  • You have a Google Workspace account
  • You need to access Gmail on behalf of multiple users
  • You’re building a server-side application
Requirements:
  • Google Workspace account (not personal Gmail)
  • Google Workspace Admin access for domain-wide delegation

Setup Steps:

1. Create a Service Account
  1. Go to IAM & Admin > Service Accounts
  2. Click CREATE SERVICE ACCOUNT
  3. Enter name: gmail-service-account
  4. Add description: Service account for Gmail API access
  5. Click CREATE AND CONTINUE, then DONE
  6. Note the service account email: gmail-service-account@your-project-id.iam.gserviceaccount.com
2. Create and Download Service Account Key
  1. Click on your service account
  2. Go to KEYS tab
  3. Click ADD KEY > Create new key
  4. Select JSON and click CREATE
  5. Save the downloaded file as credentials.json
  6. Keep this file secure!
3. Configure Domain-Wide Delegation
Requires Google Workspace Admin privileges
  1. Open credentials.json and copy the client_id value (e.g., 103635629912027933995)
  2. Go to Google Workspace Admin Console
  3. Navigate to Security > Access and data control > API Controls
  4. Click Manage Domain Wide Delegation > Add new
  5. Paste the Client ID and add scopes:
  1. Click Authorize
4. Initialize Service Account in Code

Implementation

This section walks through the essential components needed to implement Gmail integration with Timbal. For the complete example, visit our GitHub repository.

Gmail Initialization

Establish a connection to the Gmail API using your credentials. Choose the method that matches your setup:

Email monitoring

Monitor the Gmail inbox for new messages using polling:

Create a Timbal Agent for intelligent email responses

Create an Agent to generate emails responses:

Call a Timbal Agent to generate the draft

Process incoming emails by creating the prompt and invoking the Agent to generate a response:

Save the draft to the emails thread

Define the post-hook function that automatically saves the AI-generated response as a draft reply in the original email thread:

Key Features

  • Real-time Processing: Constantly polls new emails
  • Intelligent Responses: Uses AI to generate contextually appropriate draft replies
  • History Tracking: Maintains state to avoid processing duplicate emails or generated drafts

Troubleshooting

  • Missing scopes: Verify all required Gmail API scopes are included
  • OAuth issues: Check that credentials.json and token.json files exist and are valid
  • Service Account issues: Verify domain-wide delegation is configured and DELEGATED_USER has correct email
  • Rate limits: Gmail API has daily quotas. Check your usage.
  • Permission denied: For Service Accounts, ensure domain-wide delegation is authorized with correct Client ID
  • Import errors: Ensure all required packages are installed
  • File errors: Check that your credentials file exists and is properly formatted