feat(gmail): add --draft flag to +send, +reply, +reply-all, +forward

[malob]

Description

Adds a --draft flag to +send, +reply, +reply-all, and +forward. When set, calls users.drafts.create instead of users.messages.send. Message construction is identical — only the API method and metadata wrapper change.

Note: Opened as a draft because this PR is based on #589 rather than main to avoid merge conflicts, since that PR rewrites much of the mail-sending code. This should not be merged directly — only the second commit (93997d9) is new work. Happy to rebase onto main once #589 merges.

How it works

• --draft added to common_mail_args (one place, all four helpers get it)
• resolve_draft_method navigates users.drafts.create in the discovery doc
• resolve_mail_method dispatcher selects between send and draft based on the flag
• dispatch_raw_email (renamed from send_raw_email to reflect its dual role) switches the method and wraps draft metadata in the {"message": {...}} envelope required by the Drafts API
• Threaded drafts (replies and forwards) preserve threadId in the metadata
• After successful draft creation, a tip is printed to stderr with the users.drafts.send command (suppressed during --dry-run)

Related issues and PRs

• Feature request: Gmail draft-only mode for CLI+agent workflows #424 / PR feat(gmail): implement robust draft-only mode with centralized policy enforcement (#424) #499: Requests a draft-only policy that blocks all send paths for agent safety. The --draft flag handles the draft creation side, so the policy work can focus purely on enforcement — restricting which operations are allowed — without needing to implement how drafts are created.

• Is there a way to allow the CLI to draft emails but not sending them? #286: The original "can I draft without sending?" request. The --draft flag answers the drafting half; the "without sending" enforcement is Feature request: Gmail draft-only mode for CLI+agent workflows #424's territory.

• Feature request: +draft helper and CC/threading support for +send #555 (closed): Requested a +draft helper and CC/threading support for +send. CC/BCC and threading already exist via +reply/+reply-all/+forward; this PR adds the draft capability. Reporter closed the issue after learning about the existing features.

• PR fix(gmail): add HTML draft creation guidance to generated skill #568: Adds skill guidance for manually constructing RFC 2822 messages for users.drafts.create. The --draft flag makes that workflow significantly simpler — +send --draft handles all the RFC 5322 formatting, MIME encoding, and base64 automatically.

• Feature: Possibly more gfranular approach for email labeling/drafting? #508: Requests finer-grained Gmail OAuth scopes for label-only and draft-without-send access. gmail.labels covers CRUD on label definitions, but applying labels to messages requires gmail.modify, which also grants send/compose. So neither label application nor draft creation can be scoped without also granting send. Draft-without-send is not — gmail.compose bundles draft creation and sending together. Client-side enforcement like the draft-only policy from Feature request: Gmail draft-only mode for CLI+agent workflows #424 is the available workaround.

Live testing

Tested against a real Gmail account:

#	Test	Result
1	+send --draft	Draft created with DRAFT label
2	+reply --draft	Threaded draft in correct thread
3	+send --draft --dry-run	Dry-run output, no tip printed
4	+send (without --draft)	Sends normally (no regression)

Test coverage

782 total tests (6 new). New tests cover:

• build_send_metadata for all four (thread_id, draft) combinations
• resolve_draft_method discovery doc traversal
• Absence of threadId in draft metadata when no thread

Dry Run Output:

{
  "body": "{\"message\":{}}",
  "dry_run": true,
  "is_multipart_upload": true,
  "method": "POST",
  "query_params": [],
  "url": "https://gmail.googleapis.com/upload/gmail/v1/users/me/drafts"
}

Checklist:

• My code follows the AGENTS.md guidelines (no generated google-* crates).
• I have run cargo fmt --all to format the code perfectly.
• I have run cargo clippy -- -D warnings and resolved all warnings.
• I have added tests that prove my fix is effective or that my feature works.
• I have provided a Changeset file (e.g. via pnpx changeset) to document my changes.

[changeset-bot]

🦋 Changeset detected

Latest commit: 93997d9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[keramblock]

Hi @malob, thank you for taking on my issue as well as the others.
I have a small question:
Are you sure that "label management is already possible via the gmail.labels scope"?

In my testing, gmail.labels only covers CRUD on label definitions (users.labels.*), not applying labels to messages — users.messages.modify and users.threads.modify both require gmail.modify, which also grants send/compose.

This is exactly what I'm trying to avoid: I want an agent to organize my inbox with labels without it being able to create or send messages without my explicit permission.

P.S. that would be nice to force that as a draft only mode if possible to not rely on the llm not forgetting to add flag.

[malob]

You're right. I misstated that. gmail.labels covers CRUD on label definitions (users.labels.*), but applying labels to messages via users.messages.modify requires gmail.modify. And gmail.modify also grants send/compose access, so there's no scope combination that allows both label application and draft creation without also granting send. I'll update the PR description to correct this.

On the draft-only mode point: agreed, --draft as a flag is opt-in, which means the agent can forget it. A few options for enforcement:

• The policy layer from Feature request: Gmail draft-only mode for CLI+agent workflows #424 / PR feat(gmail): implement robust draft-only mode with centralized policy enforcement (#424) #499 would block send paths at the gws level, regardless of what the agent does
• Many agent frameworks support command allowlists. For example, in Claude Code you could auto-approve only the draft variants:

  {
    "permissions": {
      "allow": [
        "Bash(gws gmail +send --draft *)",
        "Bash(gws gmail +reply --draft *)",
        "Bash(gws gmail +reply-all --draft *)",
        "Bash(gws gmail +forward --draft *)"
      ]
    }
  }

  Non-draft commands would still require manual user approval. Not a hard block, but an additional safeguard.