# Google Services Integration

## Overview
Connect to the user's Google account to read and manage their Gmail and Google Calendar. The user must first connect their Google account via the `connector_manage` tool or the `/connect google` command in the web interface.

## Setup
1. Use `connector_manage` with `{action: "connect", provider: "google"}` - this opens a Google OAuth popup
2. The user grants access to Gmail and Calendar
3. Check status with `connector_manage` `{action: "status", provider: "google"}`

## Gmail Tools

For composing well-formatted messages - HTML style rules, image handling, reply-quoting - see the [email](email.md) skill; it covers both this Gmail channel and the platform email channel.

### gmail_search
Search emails using Gmail search syntax. Supports pagination - pass `page_token` from a previous result to get the next page.
- `from:alice@example.com` - emails from a specific sender
- `subject:meeting` - emails with "meeting" in subject
- `is:unread` - unread emails
- `after:2025/01/01 before:2025/02/01` - date range
- `has:attachment` - emails with attachments
- Combine: `from:boss subject:review is:unread`
- Default 10 results per page, max 50. Use `page_token` to fetch subsequent pages.

### gmail_read
Read the full content of an email by its message ID (from search results).

### gmail_send
Send a new email. **Requires user approval by default** - the user will be asked to confirm before the email is sent. The user can disable approval requirements via their connection settings.

### gmail_reply
Reply to an existing email thread. Also requires approval by default.

## Calendar Tools

### calendar_list
List all calendars the user has access to (personal, shared, etc.).

### calendar_events
List events from a calendar. Defaults to upcoming events from the primary calendar. Supports:
- Time range filtering (`time_min`, `time_max` as ISO 8601)
- Free text search (`query`)
- Specific calendar (`calendar_id`)

### calendar_create
Create a new event. **Requires user approval by default.** Supports:
- Timed events (`start_datetime`, `end_datetime`)
- All-day events (`start_date`, `end_date`)
- Location, description, attendees, timezone

### calendar_update
Update an existing event by its event ID. Requires approval.

### calendar_delete
Delete an event by its event ID. Requires approval.

## Permission System
Each service (gmail, calendar) has independent permission settings:
- **read_enabled**: on/off toggle for read access (default: on)
- **write_enabled**: on/off toggle for write access (default: on)
- **write_requires_approval**: per-call approval for each write action (default: on)

Reads never require per-call approval. Writes require approval by default - each email send or calendar event creation needs user confirmation. The user can disable per-call approval via `connector_manage` with `{action: "permissions", provider: "google"}` or the `/connect google settings` command.

## Disconnecting
Use `connector_manage` with `{action: "disconnect", provider: "google"}` to revoke access and remove stored tokens.