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:

#Send Guardrails

Block send operations globally for one run:

gog --gmail-no-send gmail send --to you@example.com --subject test --body 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:

#Reply and Reply All

The Gmail API has no reply method. Clients fetch the original message, build a complete RFC MIME message, and call messages.send. Use the first-class reply commands so gog owns that composition work:

gog gmail reply <messageId> --body-file reply.txt
gog gmail reply-all <messageId> --body-file reply.txt \
  --bcc '"Introducer" <introducer@example.com>'

Reply defaults match normal Gmail composition:

The original subject is inherited with one Re: prefix.
The original message is quoted; use --no-quote to omit it.
reply targets Reply-To when present, otherwise From.
reply-all also carries forward original To/Cc recipients while excluding

the active account and its send-as aliases.

Display names are preserved.
CID-backed inline images referenced by quoted HTML are fetched and rebuilt

as multipart/related. If a referenced MIME part is missing, the command fails instead of sending broken images.

Recipient flags modify the derived recipient set. --to, --cc, and --bcc are additive; naming an inherited recipient in a different field moves it there. Repeat --remove to subtract recipients from every field:

gog gmail reply-all <messageId> --body "Thanks all" \
  --bcc introducer@example.com \
  --remove former-participant@example.com

An explicit --subject override is supported. A changed subject cannot meet Gmail's thread-matching requirement, so gog keeps the RFC reply headers but does not force the original threadId; Gmail creates a new conversation.

Remote HTTP images remain remote references. Only MIME parts referenced with cid: are copied into the outgoing message.

gmail send --reply-to-message-id remains available as lower-level composition. It now inherits an omitted subject, but its explicit --to and --cc values retain replacement semantics and quoting remains opt-in. Prefer gmail reply or gmail reply-all for ordinary replies.

Official behavior references:

#Attachment Confirmation

gmail send --json and gmail drafts create|update --json include an attachments array when the resulting message contains attachments:

{"attachments":[{"filename":"report.pdf","size":2411233}]}

Sizes are reported in bytes. Draft updates report preserved attachments when --attach is omitted; --clear-attachments removes them and omits the field.

#Watches and Pub/Sub

Gmail watch/PubSub workflows are documented in Gmail watch.

Key command pages:

#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.