ModelBox Open Source

/

AgentKit
Core Concepts/Tools/Built-in Tools/Gmail Tool

Gmail Tool

Email functionality using Gmail API for sending and reading emails

|

The Gmail tool provides email functionality using the Gmail API for sending and reading emails.

Installation

import "github.com/model-box/agent-kit/tool/gmail"

Setup

Requirements

  1. Google Cloud Project: Enable the Gmail API
  2. OAuth 2.0 Credentials: Create OAuth credentials
  3. Access Token: Get access and refresh tokens through OAuth flow

Environment Variables

export GMAIL_ACCESS_TOKEN="your-access-token"
export GMAIL_REFRESH_TOKEN="your-refresh-token"
export GMAIL_CLIENT_ID="your-client-id"
export GMAIL_CLIENT_SECRET="your-client-secret"

Getting OAuth Tokens

Use Google's OAuth 2.0 Playground: https://developers.google.com/oauthplayground/

Required scopes:

  • https://www.googleapis.com/auth/gmail.send
  • https://www.googleapis.com/auth/gmail.readonly

Usage

package main

import (
    "context"
    "os"
    
    "github.com/model-box/agent-kit/agent"
    "github.com/model-box/agent-kit/model"
    "github.com/model-box/agent-kit/session"
    "github.com/model-box/agent-kit/tool/gmail"
)

func main() {
    // Create Gmail tools
    gmailTools := gmail.NewGmailTools()
    
    // Create model
    model := model.Model("gpt-4o").
        SetAPIKey(os.Getenv("OPENAI_API_KEY"))
    
    // Create agent with Gmail tools
    agent := agent.New().
        SetModel(model).
        SetSystemPrompt("You are a helpful email assistant.").
        AddTool(gmailTools.SendEmail()).
        AddTool(gmailTools.ListEmails())
    
    // Create session and run
    session := session.New(agent)
    ctx := context.Background()
    
    response, err := session.Run(ctx, []agent.ChatMessage{
        agent.NewUserMessage("Send an email to john@example.com with subject 'Meeting' and body 'Let's meet at 2 PM'"),
    }, nil)
    
    if err != nil {
        panic(err)
    }
    
    println(response.GetLastMessage().GetContent())
}

Available Tools

gmail_send_email

Send emails with optional formatting and attachments.

ParameterTypeRequiredDescription
tostringYesRecipient email address
subjectstringYesEmail subject
bodystringYesEmail body content
cc[]stringNoCC recipients
bcc[]stringNoBCC recipients
is_htmlboolNoWhether body is HTML (default: false)

gmail_list_emails

List and search emails from your Gmail account.

ParameterTypeRequiredDescription
querystringNoGmail search query
max_resultsintNoMaximum emails to return (1-100, default: 10)
page_tokenstringNoToken for pagination

Gmail Search Queries

  • from:sender@example.com - Emails from specific sender
  • to:recipient@example.com - Emails to specific recipient
  • subject:meeting - Emails with "meeting" in subject
  • is:unread - Unread emails
  • is:important - Important emails
  • has:attachment - Emails with attachments
  • after:2024/1/1 - Emails after specific date
  • before:2024/12/31 - Emails before specific date

Combine queries: from:boss@company.com is:unread has:attachment

Rate Limits

Gmail API quotas:

  • 250 quota units per user per second
  • 1,000,000,000 quota units per day
  • Sending an email: 100 quota units
  • Reading emails: 5 quota units per request

Security

  • Never hardcode tokens in your code
  • Use environment variables or secure secret management
  • Tokens expire; implement refresh logic for production
  • Limit scopes to minimum required permissions
Edit on GitHub