feat(gmail): add +reply, +reply-all, and +forward helpers

[HeroSizy]

Description

Closes #88 — adds first-class reply and forward support to the Gmail CLI helpers.

• +reply — Reply to a message by ID. Automatically fetches the original message, sets In-Reply-To, References, and threadId headers, quotes the original, and sends via users.messages.send.
• +reply-all — Same as +reply but addresses all original To/CC recipients. Supports --remove to drop recipients and --cc to add new ones.
• +forward — Forward a message to new recipients with a standard forwarded-message block (From, Date, Subject, To, Cc). Supports optional --body for a note above the forwarded content.

All three commands support --dry-run for safe previewing (works without auth credentials).

Address handling details:

• Prefers Reply-To over From when selecting reply recipients (mailing lists, support systems)
• Parses multi-address Reply-To headers (e.g., list@example.com, owner@example.com) and deduplicates CC against the full set
• Preserves repeated Gmail Reply-To, To, and Cc headers by concatenating values in order instead of overwriting earlier entries
• Uses RFC 5322-aware mailbox list parsing — commas inside quoted display names (e.g., "Doe, John" <john@example.com>) are handled correctly
• Uses exact normalized email extraction (not substring matching) for --remove filtering and sender exclusion — e.g., removing ann@example.com does not affect joann@example.com
• Case-insensitive email comparison throughout

Known limitation: +forward currently forwards the message text/snippet only. Full MIME forwarding with attachments will be addressed in a follow-up PR (ref #88).

New files

File	Purpose
src/helpers/gmail/reply.rs	+reply and +reply-all logic, message metadata fetching, RFC 2822 header construction
src/helpers/gmail/forward.rs	+forward logic, forwarded message formatting

Modified files

File	Change
src/helpers/gmail/mod.rs	Register new modules, add shared Gmail reply/forward helpers, and update subcommand dispatch.
src/helpers/gmail/send.rs	Reuse shared Gmail send-method resolution.
.changeset/gmail-reply-forward.md	Record the minor feature release.

Dry Run Output:

+reply:

$ gws gmail +reply --message-id 18f1a2b3c4d --body "Thanks, got it!" --dry-run
{
  "body": {
    "raw": "VG86IHNlbmRlckBleGFtcGxlLmNvbQ0KU3ViamVjdDogUmU6IE9yaWdpbmFsIHN1YmplY3QNCkluLVJlcGx5LVRvOiA8MThmMWEyYjNjNGRAZXhhbXBsZS5jb20-DQpSZWZlcmVuY2VzOiA8MThmMWEyYjNjNGRAZXhhbXBsZS5jb20-DQoNClRoYW5rcywgZ290IGl0IQ0KDQpPbiBUaHUsIDEgSmFuIDIwMjYgMDA6MDA6MDAgKzAwMDAsIHNlbmRlckBleGFtcGxlLmNvbSB3cm90ZToKPiBPcmlnaW5hbCBtZXNzYWdlIGJvZHk=",
    "threadId": "thread-18f1a2b3c4d"
  },
  "dry_run": true,
  "is_multipart_upload": false,
  "method": "POST",
  "query_params": {},
  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/send"
}

+reply-all:

$ gws gmail +reply-all --message-id 18f1a2b3c4d --body "Sounds good!" --cc eve@example.com --remove bob@example.com --dry-run
{
  "body": {
    "raw": "VG86IHNlbmRlckBleGFtcGxlLmNvbQ0KU3ViamVjdDogUmU6IE9yaWdpbmFsIHN1YmplY3QNCkluLVJlcGx5LVRvOiA8MThmMWEyYjNjNGRAZXhhbXBsZS5jb20-DQpSZWZlcmVuY2VzOiA8MThmMWEyYjNjNGRAZXhhbXBsZS5jb20-DQpDYzogeW91QGV4YW1wbGUuY29tLCBldmVAZXhhbXBsZS5jb20NCg0KU291bmRzIGdvb2QhDQoNCk9uIFRodSwgMSBKYW4gMjAyNiAwMDowMDowMCArMDAwMCwgc2VuZGVyQGV4YW1wbGUuY29tIHdyb3RlOgo-IE9yaWdpbmFsIG1lc3NhZ2UgYm9keQ==",
    "threadId": "thread-18f1a2b3c4d"
  },
  "dry_run": true,
  "is_multipart_upload": false,
  "method": "POST",
  "query_params": {},
  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/send"
}

+forward:

$ gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com --body "FYI see below" --cc carol@example.com --dry-run
{
  "body": {
    "raw": "VG86IGRhdmVAZXhhbXBsZS5jb20NClN1YmplY3Q6IEZ3ZDogT3JpZ2luYWwgc3ViamVjdA0KQ2M6IGNhcm9sQGV4YW1wbGUuY29tDQoNCkZZSSBzZWUgYmVsb3cNCg0KLS0tLS0tLS0tLSBGb3J3YXJkZWQgbWVzc2FnZSAtLS0tLS0tLS0KRnJvbTogc2VuZGVyQGV4YW1wbGUuY29tCkRhdGU6IFRodSwgMSBKYW4gMjAyNiAwMDowMDowMCArMDAwMApTdWJqZWN0OiBPcmlnaW5hbCBzdWJqZWN0ClRvOiB5b3VAZXhhbXBsZS5jb20KT3JpZ2luYWwgbWVzc2FnZSBib2R5Ci0tLS0tLS0tLS0=",
    "threadId": "thread-18f1a2b3c4d"
  },
  "dry_run": true,
  "is_multipart_upload": false,
  "method": "POST",
  "query_params": {},
  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/send"
}

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.

---

Note: This PR was developed with AI assistance (Claude). All code has been reviewed by the author.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[changeset-bot]

🦋 Changeset detected

Latest commit: 9b53621

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

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[jpoehnelt]

How does this compare to the request in #88?

[jpoehnelt]

Code duplication between reply.rs and forward.rs
Missing encode_path_segment() on the message-id in URL construction

[HeroSizy]

How does this compare to the request in #88?

This PR is a direct implementation of the feature request in #88. It adds +reply, +reply-all, and +forward as first-class helpers, covering most of the asks from that issue:

• Reply to a message by ID with automatic threading (In-Reply-To, References, threadId)
• Reply-all with proper recipient dedup
• Forward with the original message quoted
• --cc and --remove flags for adding/dropping recipients without reconstructing the list

One thing not yet covered: attachment forwarding. The current +forward quotes the original message body but doesn't carry over attachments. That could be a follow-up if this lands — happy to open a separate issue to track it.

[HeroSizy]

Code duplication between reply.rs and forward.rs Missing encode_path_segment() on the message-id in URL construction

@jpoehnelt

Thanks for the review! Both points are fixed now — forward.rs reuses OriginalMessage, fetch_message_metadata(), and send_raw_email() from reply.rs, and the message ID goes through encode_path_segment() in the URL construction.

Sorry about the initial state — I had an AI agent push before I'd properly reviewed. Everything's been cleaned up since.

A couple of questions:

1. forward.rs currently reaches into reply.rs via super::reply:: for shared types. Would you prefer those extracted into a common.rs within the gmail module?

2. We've been patching the hand-rolled mailbox parser for edge cases (escaped quotes, commas in display names, etc.) and it feels like a losing battle. Would you be open to bringing in an RFC 5322-compliant address parsing crate so we can drop the custom code entirely?

[jpoehnelt]

.

[jpoehnelt]

Nice work addressing the prior feedback — dedup and encode_path_segment() look good. A few things to address:

• Query params in URL string — fetch_message_metadata manually interpolates ?format=metadata&metadataHeaders=... into the URL. Per AGENTS.md, use reqwest .query() instead
• No From header — replies/forwards omit From:. Gmail infers it, but this breaks with aliases/send-as. Consider a --from flag or document the limitation
• Missing MIME headers — raw messages lack Content-Type: text/plain; charset=utf-8 and MIME-Version: 1.0, which can cause encoding issues with non-ASCII text
• Visibility — ReplyConfig and ForwardConfig are pub but only used within helpers::gmail; should be pub(super)
• Mailbox parser — agree with your suggestion to replace the hand-rolled split_mailbox_list with an RFC 5322 crate (mailparse etc.) in a follow-up
• CLA — cla: no label is present, needs signing before merge

[codecov]

Codecov Report

❌ Patch coverage is 77.83559% with 213 lines in your changes missing coverage. Please review.
✅ Project coverage is 56.73%. Comparing base (f6d74b0) to head (3ec8332).
⚠️ Report is 36 commits behind head on main.

Files with missing lines	Patch %	Lines
src/helpers/gmail/reply.rs	79.42%	137 Missing ⚠️
src/helpers/gmail/mod.rs	64.00%	54 Missing ⚠️
src/helpers/gmail/forward.rs	84.82%	22 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #105      +/-   ##
==========================================
+ Coverage   55.19%   56.73%   +1.54%     
==========================================
  Files          38       40       +2     
  Lines       13166    14127     +961     
==========================================
+ Hits         7267     8015     +748     
- Misses       5899     6112     +213     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces +reply, +reply-all, and +forward helper commands for the Gmail CLI, which is a great feature. The implementation is mostly solid, with good test coverage and documentation. However, I've identified a few areas for improvement concerning code structure and correctness. Specifically, there's a bug in handling repeated email headers, and some refactoring is needed to resolve circular dependencies and improve module organization. Addressing these points will enhance the maintainability and robustness of the new helpers.

[gemini-code-assist]

The forward module should not depend on the reply module for core functionalities like fetching message metadata. The fetch_message_metadata function and the OriginalMessage struct are general utilities used by both replying and forwarding. They should be moved to a more central location, like src/helpers/gmail/mod.rs, to improve code organization and reduce coupling between helpers.

[HeroSizy]

moved OriginalMessage and fetch_message_metadata into gmail/mod.rs so reply and forward share the same helper.

[HeroSizy]

can you rebase this and/or push another commit to trigger the github actions

@jpoehnelt Done, rebased

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces +reply, +reply-all, and +forward helper commands for Gmail, which is a great enhancement. The implementation is thorough, with robust handling of email headers, recipient logic, and comprehensive tests. I've found one critical issue related to parsing email headers that could lead to silently dropping recipients if the Gmail API returns multiple headers for To, Cc, or Reply-To. My review includes a suggestion to fix this.

[gemini-code-assist]

The current implementation for parsing headers overwrites values for To, Cc, and Reply-To if they appear multiple times in the API response. While the Gmail API typically combines these into a single comma-separated header, the specification allows for multiple headers. If the API were to return multiple headers for these fields, recipients would be silently dropped.

To make this more robust, you should concatenate values for these address-list headers with a comma.

            "Reply-To" => {
                if !parsed.reply_to.is_empty() { parsed.reply_to.push_str(", "); }
                parsed.reply_to.push_str(value);
            },
            "To" => {
                if !parsed.to.is_empty() { parsed.to.push_str(", "); }
                parsed.to.push_str(value);
            },
            "Cc" => {
                if !parsed.cc.is_empty() { parsed.cc.push_str(", "); }
                parsed.cc.push_str(value);
            },

[HeroSizy]

Good catch. I updated the current Gmail payload.headers[] parser to preserve repeated Reply-To, To, and Cc values in order, and added tests covering repeated address headers while keeping References behavior unchanged.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces valuable +reply, +reply-all, and +forward helper commands for the Gmail CLI, significantly improving its usability for common email workflows. The implementation is robust, with thorough handling of email headers, recipient logic, and multipart message parsing. The addition of shared helper functions in src/helpers/gmail/mod.rs is a good architectural choice. I have one suggestion to further improve maintainability by applying one of the new helpers to the existing +send command.

[gemini-code-assist]

This function can be significantly simplified by using the new send_raw_email helper function from src/helpers/gmail/mod.rs. The handle_reply and handle_forward functions already use this helper, and handle_send could do the same to avoid duplicating logic for token fetching and calling executor::execute_method.

This would also allow removing the now-redundant create_send_body function, as its logic is covered by build_raw_send_body used within send_raw_email.

The function body could be reduced to:

pub(super) async fn handle_send(
    doc: &crate::discovery::RestDescription,
    matches: &ArgMatches,
) -> Result<(), GwsError> {
    let config = parse_send_args(matches);
    let message = create_raw_message(&config.to, &config.subject, &config.body_text);
    super::send_raw_email(doc, matches, &message, None, None).await
}

[HeroSizy]

Reusing send_raw_email makes sense, but it would also change +send behavior: today it falls back to unauthenticated execution if token lookup fails, while send_raw_email returns an auth error outside --dry-run. I’d rather keep that as a separate cleanup once we decide which behavior we want for +send.