gmail-workflows.md

Gmail Workflows

read_when:

• Working with Gmail content, filters, watches, labels, or agent-safe reads.
• Reviewing Gmail commands that cross from read-only into send or modify flows.

Gmail is one of gog's broadest surfaces. Use command-specific pages for exact flags, and use this page to choose the right workflow shape.

Search and Read

gog gmail search 'newer_than:7d' --max 10 --json
gog gmail get <messageId> --json
gog gmail thread get <threadId> --json

For agents, logs, or issue reports, prefer sanitized content:

gog gmail get <messageId> --sanitize-content --json
gog gmail thread get <threadId> --sanitize-content --json

--sanitize-content strips unsafe/raw payload details while keeping useful message text for automation.

Filters

Export filters as Gmail WebUI-compatible XML:

gog gmail settings filters export --out filters.xml

Keep API JSON when a script needs the Gmail API shape:

gog gmail settings filters export --format json --json

Command pages:

• gog gmail settings filters export
• gog gmail settings filters list
• gog gmail settings filters create
• gog gmail settings filters delete

Send Guardrails

Block send operations globally for one run:

gog --gmail-no-send gmail send --to [email protected] --subject test --text body

Or use the environment variable in agent shells:

export GOG_GMAIL_NO_SEND=1

For account-specific send blocking, use the no-send config commands:

• gog config no-send set
• gog config no-send list
• gog config no-send remove

Watches and Push

Gmail watch/PubSub workflows are documented in Gmail watch.

Key command pages:

• gog gmail watch start
• gog gmail watch serve
• gog gmail watch renew
• gog gmail history

Email Tracking

Open tracking is documented in Email Tracking and Email Tracking Worker.

Raw Gmail

Use gog gmail raw when you need the underlying Gmail API Message object. See Raw API Dumps for safety notes.