---
title: "Google Drive and Gmail: REST APIs, no first-party CLI"
license: CC0-1.0
license_url: https://creativecommons.org/publicdomain/zero/1.0/
source: https://iinventedlight.com/library/notes/google-drive-gmail-api.md
upstream_source: https://developers.google.com/workspace/drive/api/guides/about-sdk
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
source_license: "CC BY 4.0 (Google Developers); restated, not copied"
license_note: "Steps are our own words from the cited docs; offered under CC0 1.0."
attribution: "How-to by iinventedlight (AI-assisted). Sources listed below."
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-10-31
date: 2026-10-31
status: published
category: agent-howto
tags: agent-howto, google-drive, gmail, oauth, rest
checked_on: 2026-10-31
tested_version: untested
sources:
  - id: S1
    title: "Google Drive API overview"
    publisher: Google
    url: https://developers.google.com/workspace/drive/api/guides/about-sdk
    accessed: 2026-10-31
    license: "CC BY 4.0, restated; page last updated 2026-09-25"
  - id: S2
    title: "Search for files and folders"
    publisher: Google
    url: https://developers.google.com/workspace/drive/api/guides/search-files
    accessed: 2026-10-31
    license: "CC BY 4.0, restated; page last updated 2026-10-12"
  - id: S3
    title: "Gmail API overview"
    publisher: Google
    url: https://developers.google.com/workspace/gmail/api/guides
    accessed: 2026-10-31
    license: "CC BY 4.0, restated; page last updated 2026-09-18"
  - id: S4
    title: "List Gmail messages"
    publisher: Google
    url: https://developers.google.com/workspace/gmail/api/guides/list-messages
    accessed: 2026-10-31
    license: "CC BY 4.0, restated; page last updated 2026-09-10"
  - id: S5
    title: "Method: users.messages.list"
    publisher: Google
    url: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list
    accessed: 2026-10-31
    license: "CC BY 4.0, restated; page last updated 2026-04-15"
---
# Google Drive and Gmail: REST APIs, no first-party CLI

> **Untested:** iinventedlight has not run the commands in this note. They are restated from the cited docs (checked 2026-10-31). Check them yourself before relying on them.

There is no official `gdrive`/`gmail` CLI in the fetched docs. Access is OAuth 2.0 + REST (or a client library). Do not send mail, share files, or print tokens.

## Summary
Drive: `GET https://www.googleapis.com/drive/v3/files` with `q=` search terms [S1][S2]. Gmail: `GET https://gmail.googleapis.com/gmail/v1/users/{userId}/messages`; list returns `id` and `threadId` only — `messages.get` loads the body [S4][S5]. Prefer read-only scopes.

## Agent access
- CLI: no first-party CLI in these docs. MCP connector: none connected here (third-party Workspace MCP servers exist; untested). API: yes (Drive v3, Gmail v1). GUI: drive.google.com / Gmail (not agent-first).
- Best route: REST with OAuth, read-only scopes, page tokens.
- Permissions: OAuth client in a Google Cloud project with the API enabled [S3][S4]. Drive file list needs a Drive scope; Gmail list needs one of `gmail.readonly`, `gmail.metadata`, `gmail.modify`, or full `mail.google.com` [S5]. Writes and send need extra scopes and the owner's approval.

## Steps (from docs, untested)
1. Drive list (OAuth access token, not an API key, for My Drive):

```
curl -X GET 'https://www.googleapis.com/drive/v3/files' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'
```

Default fields are `kind,id,name,mimeType,resourceKey` unless `fields=` is set [S2].
2. Search: `q=name contains 'budget' and trashed = false` [S2]. Folders: `mimeType = 'application/vnd.google-apps.folder'` [S2].
3. Gmail list: `users.messages.list` with `userId=me`, optional `q` like `from:someuser@example.com is:unread`, `maxResults` (default 100, max 500) [S4].
4. Then `messages.get` per id for subject/body [S4].
5. Page with `nextPageToken` until it is absent [S2][S4].

## Traps
- `parents` is **direct children only**; recurse folder IDs yourself [S2].
- List responses omit most fields unless `fields=` asks for them [S2].
- Public-folder list may use an API key; My Drive needs OAuth [S1][S2].
- Gmail list is newest-first and is not the full message [S4].
- `https://mail.google.com/` is full mailbox access; use `gmail.readonly` for reads [S5].
- Never commit `credentials.json` / `token.json`.

## What worked looks like
JSON with `files[]` or `messages[]` plus `nextPageToken` when more pages exist; HTTP 200; no refresh tokens in the log.

## Facts
- id: F1
  claim: Drive files.list without parameters lists the current user's My Drive; q filters with Drive search syntax.
  confidence: high
  date: 2026-10-31
  sources: [S2]
  license: CC0 1.0
  checked_on: 2026-10-31
- id: F2
  claim: Gmail messages.list returns message id and threadId; full content requires messages.get.
  confidence: high
  date: 2026-10-31
  sources: [S4]
  license: CC0 1.0
  checked_on: 2026-10-31