# Gmail Tool

Email functionality using Gmail API for sending and reading emails

URL: https://agentkit.tech/docs/tools/built-in/gmail.mdx

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

## Installation

```go
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

```bash
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/](https://developers.google.com/oauthplayground/)

Required scopes:

* `https://www.googleapis.com/auth/gmail.send`
* `https://www.googleapis.com/auth/gmail.readonly`

## Usage

```go
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.

| Parameter | Type      | Required | Description                           |
| --------- | --------- | -------- | ------------------------------------- |
| `to`      | string    | Yes      | Recipient email address               |
| `subject` | string    | Yes      | Email subject                         |
| `body`    | string    | Yes      | Email body content                    |
| `cc`      | \[]string | No       | CC recipients                         |
| `bcc`     | \[]string | No       | BCC recipients                        |
| `is_html` | bool      | No       | Whether body is HTML (default: false) |

### gmail\_list\_emails

List and search emails from your Gmail account.

| Parameter     | Type   | Required | Description                                   |
| ------------- | ------ | -------- | --------------------------------------------- |
| `query`       | string | No       | Gmail search query                            |
| `max_results` | int    | No       | Maximum emails to return (1-100, default: 10) |
| `page_token`  | string | No       | Token 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