feat(gmail): add first-class RFC822/EML message import command

[holgergruenhagen]

Hi, thank you for building gogcli and for the Discovery API escape hatch in #867.

A generic use case: Gmail/Workspace no longer provides server-side POP fetching for external mailboxes. A small service can read messages from another provider over IMAP, but it still needs a clean way to place the original RFC822 message into Gmail.

SMTP forwarding is not always reliable. Shared relay IP reputation or forwarding authentication can cause Gmail to reject otherwise valid messages.

gmail.users.messages.import already supports this, and gog api call can invoke it. For regular automation, however, users must Base64URL-encode each message, build JSON, and enable the generic API method.

Would you consider a first-class command such as:

gog gmail import message.eml
gog gmail import --stdin

Useful options might include --label, --internal-date-source, --never-mark-spam, and --process-for-calendar.

This command would only import an existing RFC822/EML message. IMAP fetching and synchronization would remain outside gogcli.

Thank you for considering it.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 6, 2026, 8:39 AM ET / 12:39 UTC.

Summary
Keep open for a maintainer product-direction decision: current main has no dedicated RFC822/EML Gmail import command, and its released generic API fallback still requires caller-side encoding and JSON construction. Likely related people: Peter Steinberger (high-confidence, generic API surface).

Reproducibility: not applicable. this requests a new command surface; current source confirms it is absent while a generic API path exists.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Maintainer decision needed

Question	Recommendation
Should gogcli add and maintain a dedicated Gmail RFC822/EML import command instead of relying on the released generic Discovery API caller?	Sponsor a narrow import command: Add file/stdin RFC822 input and a small validated set of Gmail import flags with live Gmail API proof.

Why: Current main offers a functional but less ergonomic generic path; VISION.md requires discussion before adding a specialized API surface, and the choice sets a permanent command contract.

Next step
A maintainer must choose whether the released generic API fallback remains the supported route or becomes a permanent Gmail command.

Review details

Best possible solution:

If sponsored, add one narrow Gmail import primitive that reads file/stdin bytes, Base64URL-encodes RFC822 source, exposes only validated import options, and proves dry-run plus live import with a safe test mailbox.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this requests a new command surface; current source confirms it is absent while a generic API path exists.

Is this the best way to solve the issue?

Unclear: a narrow dedicated wrapper could remove repeated encoding work, but maintainers must first decide whether that specialized Gmail API surface warrants permanent support.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A first-class write command would create a permanent Gmail API contract whose flag set, safety controls, and live-provider validation need explicit maintainer agreement.

Codex review notes: model internal, reasoning high; reviewed against 27af1477df4a.

Label changes

Label justifications:

• P3: This is a useful but niche ergonomic feature request with a released generic workaround, not broken existing behavior.

Evidence reviewed

What I checked:

• Current generic fallback: The generic API command accepts a JSON body or JSON file, so the user must still Base64URL-encode RFC822 and wrap it in JSON outside the CLI. (internal/cmd/api.go:45, 27af1477df4a)
• No dedicated import surface: A current-tree search found RFC822/EML export and raw-message support but no Gmail import command or messages.import implementation. (internal/cmd/gmail.go:1, 27af1477df4a)
• Generic fallback provenance: Commit 0122f09 introduced Discovery-backed method access and shipped in v0.31.0; current main independently retains the generic API command. (internal/cmd/api.go:40, 0122f09d84e5)
• Product scope: VISION.md permits small useful Gmail primitives but places new API surfaces and unusual or hard-to-validate features in the discussion-first category. (VISION.md:13, 27af1477df4a)
• Maturity helper unavailable: The required helper could not locate qa/maturity-scores.yaml in this checkout, so maturity was not inferred.

Likely related people:

• Peter Steinberger: Authored the merged Discovery API surface that is the current workaround and is the dominant contributor in sampled API/Gmail command history. (role: introduced generic API fallback and recent command-area contributor; confidence: high; commits: 0122f09d84e5, 4747fb05a429; files: internal/cmd/api.go, internal/cmd/gmail.go, docs/commands/gog-api-call.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.