---
name: gog-gmail
description: "Gmail via the gog CLI: search threads/messages, read sanitized message bodies, manage labels and drafts, archive/trash, batch modify, and (only when asked) send mail. Use for Gmail automation that needs stable JSON and explicit account selection."
---

# gog gmail

Gmail reads and writes with parseable output. Pick the account on every call
with `--account <email>` (or set `GOG_ACCOUNT`). Verify auth first with
`gog auth list --check --json --no-input`.

## Reads

```bash
gog --account you@example.com gmail search 'newer_than:7d' --max 10 --json --wrap-untrusted
gog --account you@example.com gmail get <messageId> --sanitize-content --json --wrap-untrusted
gog --account you@example.com gmail thread get <threadId> --sanitize-content --json --wrap-untrusted
gog --account you@example.com gmail unread --json
gog --account you@example.com gmail labels list --json
gog --account you@example.com gmail drafts list --json
```

Use Gmail query syntax for `search` (`from:`, `subject:`, `has:attachment`,
`newer_than:`). Prefer `--sanitize-content` for bodies unless raw payloads are
explicitly needed.

## Writes

```bash
gog --account you@example.com gmail drafts create --to a@b.com --subject "..." --body "..."
gog --account you@example.com gmail archive <messageId>
gog --account you@example.com gmail trash <messageId>
gog --account you@example.com gmail labels create "Project/Acme"
gog --account you@example.com gmail batch modify --query 'older_than:1y' --add-label TRASH --dry-run
```

Sending is separate and guarded — only when the user asked to send:

```bash
gog --account you@example.com gmail send --to a@b.com --subject "..." --body "..."
gog --account you@example.com gmail drafts send <draftId>
```

## Safety

- Keep `--gmail-no-send` (or `GOG_GMAIL_NO_SEND=1`) on unless sending mail is the
  task. It blocks `send`/`drafts send` even if invoked by mistake.
- Label **IDs** are case-sensitive opaque tokens; only label *names* are case-folded.
- `--dry-run` first on `batch modify`/`batch delete`; trash is reversible, batch
  delete is not — it needs `--force`.
- stdout is data (`--json`/`--plain`); hints go to stderr. `--no-input` in automation.

## Discovery

`gog gmail --help` · `gog gmail <cmd> --help` · `gog schema gmail <cmd> --json`
Reference: <https://gogcli.sh/>
