- Connect to the Gmail API to retrieve incoming messages
- Use agents to generate draft replies
Setup Requirements
Installing Packages
Installing Packages
Install the required Google API client libraries:
Enabling Gmail API to your account
Enabling Gmail API to your account
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
- Navigate to APIs & Services > Library
- Search for “Gmail API”
- 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:3. Generate Access Token
Run this script once to generate This will open a browser window for Google sign-in.4. Initialize in Code
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- Go to APIs & Services > Credentials
- Click Create Credentials > OAuth client ID
- Choose Desktop app as the application type
- Download the credentials JSON file and save it as
credentials.json
token.json: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- Go to IAM & Admin > Service Accounts
- Click CREATE SERVICE ACCOUNT
- Enter name:
gmail-service-account - Add description:
Service account for Gmail API access - Click CREATE AND CONTINUE, then DONE
- Note the service account email:
gmail-service-account@your-project-id.iam.gserviceaccount.com
- Click on your service account
- Go to KEYS tab
- Click ADD KEY > Create new key
- Select JSON and click CREATE
- Save the downloaded file as
credentials.json - Keep this file secure!
Requires Google Workspace Admin privileges
- Open
credentials.jsonand copy theclient_idvalue (e.g.,103635629912027933995) - Go to Google Workspace Admin Console
- Navigate to Security > Access and data control > API Controls
- Click Manage Domain Wide Delegation > Add new
- Paste the Client ID and add scopes:
- Click Authorize
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:- OAuth 2.0
- Service Account
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:Script 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
Next Steps
This example demonstrates a simple implementation to showcase Timbal’s capabilities for Gmail automation. For a more sophisticated solution, consider configuring Gmail to send notifications to a Pub/Sub topic when new messages arrive.Troubleshooting
Authentication Issues
Authentication Issues
- Missing scopes: Verify all required Gmail API scopes are included
- OAuth issues: Check that
credentials.jsonandtoken.jsonfiles exist and are valid - Service Account issues: Verify domain-wide delegation is configured and
DELEGATED_USERhas correct email
API Connection Problems
API Connection Problems
- 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
Code Issues
Code Issues
- Import errors: Ensure all required packages are installed
- File errors: Check that your credentials file exists and is properly formatted