> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace Plugin

> Gmail, Google Calendar, and Google Drive operations.

**Plugin ID:** `google-workspace` | **Auth:** OAuth2 (provider id `google`, the Better Auth social provider) | **Scopes:** `gmail.modify`, `calendar`, `drive.readonly`

<Note>
  This plugin's tool paths use service-specific prefixes (`gmail.*`, `calendar.*`) rather than the plugin ID `google-workspace`. This is intentional -- tools are namespaced by the Google service they interact with.
</Note>

<Note>
  **Google Cloud APIs must be enabled.** The OAuth client's underlying Google Cloud project needs Gmail API and Google Calendar API enabled in the API Library before live calls succeed; otherwise responses come back as `403: API has not been used in project ... before or it is disabled`.
</Note>

Handlers call the public Google APIs at `https://gmail.googleapis.com/gmail/v1/users/me/*` and `https://www.googleapis.com/calendar/v3/*`. `gmail.messages.list` does a `messages.list` then a per-message metadata fetch (`format=metadata` with `Subject`/`From`/`Date` headers). `gmail.messages.read` fetches `format=full`, walks the MIME tree for the first `text/plain` part, and decodes from base64url. `gmail.drafts.create` builds an RFC-822 message, base64url-encodes the raw payload, and POSTs to `users/me/drafts`. `calendar.events.list` uses `singleEvents=true` and `orderBy=startTime`, defaulting `timeMin` to "now".

## Tools

### gmail.messages.list

**Name:** List Gmail Messages

Search and list Gmail messages matching a query.

| Parameter | Type      | Required | Default | Description                                          |
| --------- | --------- | -------- | ------- | ---------------------------------------------------- |
| `query`   | `string`  | Yes      | --      | Gmail search query (same syntax as Gmail search bar) |
| `limit`   | `integer` | No       | `10`    | Max messages to return                               |

**Output:**

```json theme={null}
{
  "messages": [
    {
      "id": "msg-001",
      "threadId": "thread-001",
      "subject": "Weekly report",
      "from": "alice@example.com",
      "snippet": "Here is the weekly report...",
      "date": "2025-01-15T12:00:00Z"
    }
  ]
}
```

***

### gmail.messages.read

**Name:** Read Gmail Message

Read the full content of a Gmail message by ID.

| Parameter   | Type     | Required | Description      |
| ----------- | -------- | -------- | ---------------- |
| `messageId` | `string` | Yes      | Gmail message ID |

**Output:**

```json theme={null}
{
  "id": "msg-001",
  "subject": "Weekly report",
  "from": "alice@example.com",
  "to": "bob@example.com",
  "body": "Here is the weekly report...",
  "date": "2025-01-15T12:00:00Z"
}
```

***

### gmail.drafts.create

**Name:** Create Gmail Draft | **Destructive:** Yes

Create a draft email in Gmail. Requires user approval.

| Parameter | Type     | Required | Description     |
| --------- | -------- | -------- | --------------- |
| `to`      | `string` | Yes      | Recipient email |
| `subject` | `string` | Yes      | Email subject   |
| `body`    | `string` | Yes      | Email body      |
| `cc`      | `string` | No       | CC recipient    |

**Output:**

```json theme={null}
{
  "draftId": "draft-001"
}
```

***

### calendar.events.list

**Name:** List Calendar Events

List upcoming Google Calendar events.

| Parameter    | Type      | Required | Default     | Description          |
| ------------ | --------- | -------- | ----------- | -------------------- |
| `calendarId` | `string`  | No       | `"primary"` | Calendar ID          |
| `timeMin`    | `string`  | No       | --          | ISO 8601 start bound |
| `timeMax`    | `string`  | No       | --          | ISO 8601 end bound   |
| `limit`      | `integer` | No       | `10`        | Max events to return |

**Output:**

```json theme={null}
{
  "events": [
    {
      "id": "event-001",
      "summary": "Team standup",
      "start": "2025-01-15T09:00:00Z",
      "end": "2025-01-15T09:30:00Z",
      "attendees": ["alice@example.com", "bob@example.com"]
    }
  ]
}
```