Gmail Tools

The Gmail Tools integration enables your Forjinn AI agents to interact with Gmail accounts through the Gmail API. This powerful toolset allows for comprehensive email management including drafts, messages, labels, and threads - all working completely offline once configured.

What are Gmail Tools?

• Type: LangChain tool integration for Gmail API
• Category: Communication & Email Management
• Authentication: OAuth2 with refresh token support
• Offline Support: ✅ Full offline operation after initial setup

Available Operations

Draft Management

• List Drafts - Retrieve all draft emails
• Create Draft - Create new email drafts
• Get Draft - Retrieve specific draft by ID
• Update Draft - Modify existing drafts
• Send Draft - Send draft emails
• Delete Draft - Remove drafts permanently

Message Operations

• List Messages - Query inbox with Gmail search syntax
• Get Message - Retrieve specific messages
• Send Message - Send emails directly
• Modify Message - Add/remove labels from messages
• Trash Message - Move messages to trash
• Untrash Message - Restore messages from trash
• Delete Message - Permanently delete messages

Label Management

• List Labels - Get all available labels
• Get Label - Retrieve specific label details
• Create Label - Create custom labels
• Update Label - Modify label properties
• Delete Label - Remove labels

Thread Operations

• List Threads - Query conversation threads
• Get Thread - Retrieve complete thread details
• Modify Thread - Manage thread labels
• Trash Thread - Move entire threads to trash
• Untrash Thread - Restore threads from trash
• Delete Thread - Permanently delete threads

Prerequisites

1. Gmail OAuth2 Credentials

Set up Gmail OAuth2 credentials in Forjinn:

{
  "credentialName": "gmailOAuth2",
  "clientId": "your-google-client-id",
  "clientSecret": "your-google-client-secret",
  "accessToken": "generated-access-token",
  "refreshToken": "generated-refresh-token"
}

2. Google Cloud Console Setup

1. Create a project in Google Cloud Console
2. Enable Gmail API
3. Create OAuth2 credentials
4. Add authorized redirect URIs
5. Configure consent screen

Configuration

Basic Setup

1. Add Gmail Tool Node

   • Drag Gmail tool from Tools category
   • Select credential: gmailOAuth2

2. Choose Operation Type

   • Drafts
   • Messages
   • Labels
   • Threads

3. Select Actions

   • Choose specific operations for your use case
   • Configure parameters for each action

Advanced Parameters

Draft Operations

# List Drafts
maxResults: 100  # Maximum drafts to return

# Create/Update Draft
to: "recipient@example.com,recipient2@example.com"
subject: "Email Subject"
body: "Email content in HTML or plain text"
cc: "cc@example.com"
bcc: "bcc@example.com"

# Draft Management
draftId: "draft_id_string"  # Required for get/update/send/delete

Message Operations

# List Messages
maxResults: 100
query: "is:unread from:example@gmail.com"  # Gmail search syntax

# Send Message
to: "recipient@example.com"
subject: "Subject"
body: "Message content"
cc: "cc@example.com"
bcc: "bcc@example.com"

# Message Management
messageId: "message_id_string"
addLabelIds: "INBOX,STARRED"  # Comma-separated
removeLabelIds: "UNREAD,SPAM"

Label Operations

# Create/Update Label
labelName: "Important Projects"
labelColor: "#ff0000"  # Hex color code

# Label Management
labelId: "label_id_string"

Thread Operations

# List Threads
maxResults: 100
query: "is:unread has:attachment"

# Thread Management
threadId: "thread_id_string"
addLabelIds: "IMPORTANT,WORK"
removeLabelIds: "UNREAD"

Usage Examples

Example 1: Email Automation Agent

# Agent Flow Configuration
Agent Type: Gmail
Selected Actions:
  - listMessages
  - sendMessage
  - createLabel

Parameters:
  messageQuery: "is:unread label:support"
  maxResults: 50

Use Case: Automatically process support emails and send responses.

Example 2: Email Organization System

# Multi-Action Configuration
Actions:
  - listMessages
  - modifyMessage
  - createLabel

Workflow:
  1. List unread emails
  2. Analyze content with LLM
  3. Apply appropriate labels
  4. Mark as processed

Example 3: Draft Management Workflow

# Draft Workflow
Actions:
  - createDraft
  - updateDraft
  - sendDraft

Process:
  1. Create draft from template
  2. Populate with dynamic content
  3. Review and send

Gmail Search Syntax

Use Gmail's powerful search syntax for filtering:

# Common Search Operators
is:unread                    # Unread messages
from:sender@example.com      # From specific sender
to:recipient@example.com     # To specific recipient
subject:"Important Update"   # Subject contains text
has:attachment              # Has attachments
label:work                  # Has specific label
after:2024/1/1             # After specific date
before:2024/12/31          # Before specific date
larger:10M                 # Larger than 10MB

Error Handling

Common Issues

1. Authentication Errors

   Error: Gmail API Error 401: Unauthorized
   Solution: Refresh OAuth2 tokens or re-authenticate
   

2. Rate Limiting

   Error: Gmail API Error 429: Too Many Requests
   Solution: Implement retry logic with exponential backoff
   

3. Invalid Parameters

   Error: Message ID is required
   Solution: Ensure required IDs are provided for operations
   

Best Practices

• Token Management: Implement automatic token refresh
• Error Handling: Use try-catch blocks for API calls
• Rate Limiting: Respect Gmail API quotas
• Batch Operations: Group multiple operations when possible

Security Considerations

Data Privacy

• All email data processed locally in offline mode
• No data transmitted to external servers
• OAuth2 tokens stored securely in Forjinn credentials

Access Control

• Use least-privilege OAuth2 scopes
• Regularly rotate access tokens
• Monitor API usage and access logs

Compliance

• Ensure GDPR/privacy compliance for email processing
• Implement data retention policies
• Audit email access and modifications

Integration Patterns

1. Customer Support Automation

Trigger: New support email
Actions:
  - Analyze email content
  - Create appropriate labels
  - Generate draft response
  - Notify support team

2. Email Newsletter Management

Trigger: Scheduled workflow
Actions:
  - Create newsletter draft
  - Populate with dynamic content
  - Send to subscriber list
  - Track delivery status

3. Email Analytics

Trigger: Daily report
Actions:
  - List messages by date range
  - Analyze email patterns
  - Generate insights report
  - Send summary email

Troubleshooting

Setup Issues

1. OAuth2 Configuration

   • Verify Google Cloud Console settings
   • Check redirect URIs
   • Ensure Gmail API is enabled

2. Credential Problems

   • Validate client ID and secret
   • Refresh expired tokens
   • Check scope permissions

Runtime Issues

1. API Errors

   • Check Gmail API quotas
   • Verify message/thread IDs
   • Validate search queries

2. Performance

   • Optimize query parameters
   • Use pagination for large results
   • Implement caching strategies

API Limits & Quotas

Gmail API Limits

• Requests per day: 1 billion
• Requests per 100 seconds: 250,000
• Requests per 100 seconds per user: 25,000

Optimization Tips

• Use batch requests when possible
• Implement intelligent caching
• Filter results at API level
• Use partial responses for large datasets

Advanced Features

Custom Email Templates

# Template Configuration
templates:
  support_response:
    subject: "Re: {{original_subject}}"
    body: |
      Dear {{customer_name}},
      
      Thank you for contacting us regarding {{issue_type}}.
      {{ai_generated_response}}
      
      Best regards,
      Support Team

Automated Workflows

# Workflow Example
name: "Email Triage System"
trigger: "New email received"
steps:
  1. Classify email category
  2. Extract key information
  3. Route to appropriate team
  4. Create tracking ticket
  5. Send acknowledgment

Related Documentation

• Adding Credentials
• LangChain Integration
• Available Tools
• Agent Creation Guide

---

Note: Gmail Tools require proper OAuth2 setup and Gmail API access. Ensure compliance with Google's API terms of service and your organization's email policies.