feat(gmail): add thread IDs to draft replies

* feat(gmail): add --thread-id to drafts create/update for parity with send

`gmail send` accepts --thread-id ("uses latest message for headers") but
`gmail drafts create`/`update` only accepted --reply-to-message-id, so there
was no thread-aware reply path when composing a draft. Callers who knew the
thread (not the latest message id) had nowhere to put it; passing a thread id
into --reply-to-message-id silently mis-threads — the draft lands in the thread
via subject fallback but In-Reply-To/References never anchor to the parent's
RFC822 Message-Id, and there's no error.

Wire --thread-id into both draft commands, reusing the existing
prepareComposeReply/fetchReplyInfo thread path (selects the latest thread
message for reply headers):

- Mutually exclusive with --reply-to-message-id (matches `send`).
- --quote now accepts a thread target too.
- On update, a caller-provided --thread-id overrides the draft's existing
  thread; the existing-draft thread fallback is preserved when omitted.
- dry-run/JSON gains a thread_id field.

Tests: create resolves to the thread's latest message and stamps threadId +
In-Reply-To/References; mutual-exclusion guard; update override. Regenerated
command docs.

Live-verified (redacted): `gog gmail drafts create --thread-id <T>` produced a
draft whose In-Reply-To/References equal the thread's latest message Message-Id
and whose threadId == <T> (scratch draft created, verified, deleted).

Closes #673.

* docs: add changelog for Gmail draft thread IDs

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>

Author: chrischall

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Added
 
+- Gmail: add `--thread-id` to `gmail drafts create` and `gmail drafts update` so drafts can reply within a thread using the latest message headers. (#673, #674) — thanks @chrischall.
+
 ### Fixed
 
 ## 0.21.0 - 2026-06-01

docs/commands/gog-gmail-drafts-create.md

@@ -40,12 +40,13 @@ gog gmail (mail,email) drafts (draft) create (add,new) [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
-| `--quote` | `bool` |  | Include quoted original message in reply (requires --reply-to-message-id) |
+| `--quote` | `bool` |  | Include quoted original message in reply (requires --reply-to-message-id or --thread-id) |
 | `--reply-to` | `string` |  | Reply-To header address |
 | `--reply-to-message-id` | `string` |  | Reply to Gmail message ID (sets In-Reply-To/References and thread) |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
 | `--subject` | `string` |  | Subject (required) |
+| `--thread-id` | `string` |  | Reply within a Gmail thread (uses latest message for headers) |
 | `--to` | `string` |  | Recipients (comma-separated) |
 | `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
 | `--version` | `kong.VersionFlag` |  | Print version and exit |

docs/commands/gog-gmail-drafts-update.md

@@ -46,6 +46,7 @@ gog gmail (mail,email) drafts (draft) update (edit,set) <draftId> [flags]
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
 | `--subject` | `string` |  | Subject (required) |
+| `--thread-id` | `string` |  | Reply within a Gmail thread (uses latest message for headers); overrides the draft's existing thread |
 | `--to` | `*string` |  | Recipients (comma-separated; omit to keep existing) |
 | `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
 | `--version` | `kong.VersionFlag` |  | Print version and exit |

internal/cmd/gmail_drafts.go

@@ -256,8 +256,9 @@ type GmailDraftsCreateCmd struct {
 	BodyFile         string   `name:"body-file" help:"Body file path (plain text; '-' for stdin)"`
 	BodyHTML         string   `name:"body-html" help:"Body (HTML; optional)"`
 	ReplyToMessageID string   `name:"reply-to-message-id" help:"Reply to Gmail message ID (sets In-Reply-To/References and thread)"`
+	ThreadID         string   `name:"thread-id" help:"Reply within a Gmail thread (uses latest message for headers)"`
 	ReplyTo          string   `name:"reply-to" help:"Reply-To header address"`
-	Quote            bool     `name:"quote" help:"Include quoted original message in reply (requires --reply-to-message-id)"`
+	Quote            bool     `name:"quote" help:"Include quoted original message in reply (requires --reply-to-message-id or --thread-id)"`
 	Attach           []string `name:"attach" help:"Attachment file path (repeatable)"`
 	From             string   `name:"from" help:"Send from this email address (must be a verified send-as alias)"`
 }
@@ -442,8 +443,12 @@ func (c *GmailDraftsCreateCmd) Run(ctx context.Context, flags *RootFlags) error
 		return err
 	}
 	replyToMessageID := normalizeGmailMessageID(c.ReplyToMessageID)
-	if c.Quote && replyToMessageID == "" {
-		return usage("--quote requires --reply-to-message-id")
+	threadID := normalizeGmailThreadID(c.ThreadID)
+	if replyToMessageID != "" && threadID != "" {
+		return usage("use only one of --reply-to-message-id or --thread-id")
+	}
+	if c.Quote && replyToMessageID == "" && threadID == "" {
+		return usage("--quote requires --reply-to-message-id or --thread-id")
 	}
 
 	attachPaths, err := expandComposeAttachmentPaths(c.Attach)
@@ -459,7 +464,7 @@ func (c *GmailDraftsCreateCmd) Run(ctx context.Context, flags *RootFlags) error
 		Body:             body,
 		BodyHTML:         c.BodyHTML,
 		ReplyToMessageID: replyToMessageID,
-		ReplyToThreadID:  "",
+		ReplyToThreadID:  threadID,
 		ReplyTo:          c.ReplyTo,
 		Quote:            c.Quote,
 		Attach:           attachPaths,
@@ -480,6 +485,7 @@ func (c *GmailDraftsCreateCmd) Run(ctx context.Context, flags *RootFlags) error
 		"body_len":            len(strings.TrimSpace(input.Body)),
 		"body_html_len":       len(strings.TrimSpace(input.BodyHTML)),
 		"reply_to_message_id": strings.TrimSpace(input.ReplyToMessageID),
+		"thread_id":           strings.TrimSpace(input.ReplyToThreadID),
 		"reply_to":            strings.TrimSpace(input.ReplyTo),
 		"quote":               input.Quote,
 		"from":                strings.TrimSpace(input.From),
@@ -515,6 +521,7 @@ type GmailDraftsUpdateCmd struct {
 	BodyFile         string   `name:"body-file" help:"Body file path (plain text; '-' for stdin)"`
 	BodyHTML         string   `name:"body-html" help:"Body (HTML; optional)"`
 	ReplyToMessageID string   `name:"reply-to-message-id" help:"Reply to Gmail message ID (sets In-Reply-To/References and thread)"`
+	ThreadID         string   `name:"thread-id" help:"Reply within a Gmail thread (uses latest message for headers); overrides the draft's existing thread"`
 	ReplyTo          string   `name:"reply-to" help:"Reply-To header address"`
 	Quote            bool     `name:"quote" help:"Include quoted original message in reply"`
 	Attach           []string `name:"attach" help:"Attachment file path (repeatable)"`
@@ -540,6 +547,10 @@ func (c *GmailDraftsUpdateCmd) Run(ctx context.Context, flags *RootFlags) error
 		return err
 	}
 	replyToMessageID := normalizeGmailMessageID(c.ReplyToMessageID)
+	threadID := normalizeGmailThreadID(c.ThreadID)
+	if replyToMessageID != "" && threadID != "" {
+		return usage("use only one of --reply-to-message-id or --thread-id")
+	}
 
 	attachPaths, err := expandComposeAttachmentPaths(c.Attach)
 	if err != nil {
@@ -577,6 +588,7 @@ func (c *GmailDraftsUpdateCmd) Run(ctx context.Context, flags *RootFlags) error
 		"body_len":            len(strings.TrimSpace(input.Body)),
 		"body_html_len":       len(strings.TrimSpace(input.BodyHTML)),
 		"reply_to_message_id": strings.TrimSpace(input.ReplyToMessageID),
+		"thread_id":           strings.TrimSpace(threadID),
 		"reply_to":            strings.TrimSpace(input.ReplyTo),
 		"quote":               input.Quote,
 		"from":                strings.TrimSpace(input.From),
@@ -610,19 +622,27 @@ func (c *GmailDraftsUpdateCmd) Run(ctx context.Context, flags *RootFlags) error
 		to = existingTo
 	}
 
+	// A caller-provided --thread-id targets that thread for reply headers,
+	// overriding the draft's own existing thread; otherwise fall back to the
+	// existing draft thread as before.
+	targetThreadID := existingThreadID
+	if threadID != "" {
+		targetThreadID = threadID
+	}
+
 	replyToThreadID := ""
 	if c.Quote && strings.TrimSpace(replyToMessageID) == "" {
-		resolvedMessageID, resolveErr := resolveQuoteReplyTargetMessageID(ctx, svc, existingThreadID, account, existingMessageID)
+		resolvedMessageID, resolveErr := resolveQuoteReplyTargetMessageID(ctx, svc, targetThreadID, account, existingMessageID)
 		if resolveErr != nil {
 			return resolveErr
 		}
 		replyToMessageID = resolvedMessageID
 	}
 	if strings.TrimSpace(replyToMessageID) == "" {
-		replyToThreadID = existingThreadID
+		replyToThreadID = targetThreadID
 	}
 	if c.Quote && strings.TrimSpace(replyToMessageID) == "" && strings.TrimSpace(replyToThreadID) == "" {
-		return usage("--quote requires --reply-to-message-id or existing draft thread")
+		return usage("--quote requires --reply-to-message-id or --thread-id or existing draft thread")
 	}
 
 	input.To = to

internal/cmd/gmail_drafts_cmd_test.go

@@ -1402,3 +1402,187 @@ func TestGmailDraftsUpdateCmd_QuoteRequiresReplyContext(t *testing.T) {
 		t.Fatalf("expected quote/reply context validation error, got %v", err)
 	}
 }
+
+// --thread-id on drafts create anchors In-Reply-To/References to the thread's
+// latest message and stamps the draft's threadId (parity with `gmail send`).
+func TestGmailDraftsCreateCmd_WithThreadID(t *testing.T) {
+	origNew := newGmailService
+	t.Cleanup(func() { newGmailService = origNew })
+
+	var posted gmail.Draft
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.Contains(r.URL.Path, "/gmail/v1/users/me/threads/t1") && r.Method == http.MethodGet:
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"id": "t1",
+				"messages": []map[string]any{
+					{
+						"id": "old", "threadId": "t1", "internalDate": "1000",
+						"payload": map[string]any{"headers": []map[string]any{
+							{"name": "Message-ID", "value": "<old@id>"},
+						}},
+					},
+					{
+						"id": "latest", "threadId": "t1", "internalDate": "2000",
+						"payload": map[string]any{"headers": []map[string]any{
+							{"name": "Message-ID", "value": "<latest@id>"},
+							{"name": "References", "value": "<r1@id>"},
+						}},
+					},
+				},
+			})
+			return
+		case strings.Contains(r.URL.Path, "/gmail/v1/users/me/drafts") && r.Method == http.MethodPost:
+			body, _ := io.ReadAll(r.Body)
+			if unmarshalErr := json.Unmarshal(body, &posted); unmarshalErr != nil {
+				t.Fatalf("unmarshal: %v", unmarshalErr)
+			}
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{"id": "d1", "message": map[string]any{"id": "m2", "threadId": "t1"}})
+			return
+		default:
+			http.NotFound(w, r)
+			return
+		}
+	}))
+	defer srv.Close()
+
+	svc, err := gmail.NewService(context.Background(),
+		option.WithoutAuthentication(), option.WithHTTPClient(srv.Client()), option.WithEndpoint(srv.URL+"/"))
+	if err != nil {
+		t.Fatalf("NewService: %v", err)
+	}
+	newGmailService = func(context.Context, string) (*gmail.Service, error) { return svc, nil }
+
+	flags := &RootFlags{Account: "a@b.com"}
+	u, uiErr := ui.New(ui.Options{Stdout: io.Discard, Stderr: io.Discard, Color: "never"})
+	if uiErr != nil {
+		t.Fatalf("ui.New: %v", uiErr)
+	}
+	ctx := outfmt.WithMode(ui.WithUI(context.Background(), u), outfmt.Mode{JSON: true})
+
+	_ = captureStdout(t, func() {
+		if runErr := runKong(t, &GmailDraftsCreateCmd{}, []string{
+			"--to", "a@example.com", "--subject", "Re: hi", "--body", "Hello", "--thread-id", "t1",
+		}, ctx, flags); runErr != nil {
+			t.Fatalf("execute: %v", runErr)
+		}
+	})
+
+	if posted.Message == nil {
+		t.Fatal("no draft posted")
+	}
+	if posted.Message.ThreadId != "t1" {
+		t.Fatalf("expected draft threadId t1, got %q", posted.Message.ThreadId)
+	}
+	raw, decErr := base64.RawURLEncoding.DecodeString(posted.Message.Raw)
+	if decErr != nil {
+		t.Fatalf("decode raw: %v", decErr)
+	}
+	s := string(raw)
+	if !strings.Contains(s, "In-Reply-To: <latest@id>") {
+		t.Fatalf("In-Reply-To not anchored to latest thread message:\n%s", s)
+	}
+	if !strings.Contains(s, "References:") || !strings.Contains(s, "<latest@id>") {
+		t.Fatalf("References not built from latest thread message:\n%s", s)
+	}
+}
+
+// --thread-id and --reply-to-message-id are mutually exclusive on drafts create.
+func TestGmailDraftsCreateCmd_ThreadIDAndMessageIDMutuallyExclusive(t *testing.T) {
+	flags := &RootFlags{Account: "a@b.com"}
+	u, uiErr := ui.New(ui.Options{Stdout: io.Discard, Stderr: io.Discard, Color: "never"})
+	if uiErr != nil {
+		t.Fatalf("ui.New: %v", uiErr)
+	}
+	ctx := ui.WithUI(context.Background(), u)
+	err := runKong(t, &GmailDraftsCreateCmd{}, []string{
+		"--subject", "S", "--body", "B", "--reply-to-message-id", "m1", "--thread-id", "t1",
+	}, ctx, flags)
+	if err == nil || !strings.Contains(err.Error(), "use only one of --reply-to-message-id or --thread-id") {
+		t.Fatalf("expected mutual-exclusion error, got %v", err)
+	}
+}
+
+// A caller-provided --thread-id on drafts update overrides the draft's own
+// existing thread when anchoring reply headers.
+func TestGmailDraftsUpdateCmd_WithThreadIDOverridesExisting(t *testing.T) {
+	origNew := newGmailService
+	t.Cleanup(func() { newGmailService = origNew })
+
+	var posted gmail.Draft
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.Contains(r.URL.Path, "/gmail/v1/users/me/drafts/d1") && r.Method == http.MethodGet:
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"id":      "d1",
+				"message": map[string]any{"id": "m1", "threadId": "te"},
+			})
+			return
+		case strings.Contains(r.URL.Path, "/gmail/v1/users/me/threads/t1") && r.Method == http.MethodGet:
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"id": "t1",
+				"messages": []map[string]any{
+					{
+						"id": "latest", "threadId": "t1", "internalDate": "2000",
+						"payload": map[string]any{"headers": []map[string]any{
+							{"name": "Message-ID", "value": "<latest@id>"},
+						}},
+					},
+				},
+			})
+			return
+		case strings.Contains(r.URL.Path, "/gmail/v1/users/me/drafts/d1") && r.Method == http.MethodPut:
+			body, _ := io.ReadAll(r.Body)
+			if unmarshalErr := json.Unmarshal(body, &posted); unmarshalErr != nil {
+				t.Fatalf("unmarshal: %v", unmarshalErr)
+			}
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{"id": "d1", "message": map[string]any{"id": "m2", "threadId": "t1"}})
+			return
+		default:
+			http.NotFound(w, r)
+			return
+		}
+	}))
+	defer srv.Close()
+
+	svc, err := gmail.NewService(context.Background(),
+		option.WithoutAuthentication(), option.WithHTTPClient(srv.Client()), option.WithEndpoint(srv.URL+"/"))
+	if err != nil {
+		t.Fatalf("NewService: %v", err)
+	}
+	newGmailService = func(context.Context, string) (*gmail.Service, error) { return svc, nil }
+
+	flags := &RootFlags{Account: "a@b.com"}
+	u, uiErr := ui.New(ui.Options{Stdout: io.Discard, Stderr: io.Discard, Color: "never"})
+	if uiErr != nil {
+		t.Fatalf("ui.New: %v", uiErr)
+	}
+	ctx := outfmt.WithMode(ui.WithUI(context.Background(), u), outfmt.Mode{JSON: true})
+
+	_ = captureStdout(t, func() {
+		if runErr := runKong(t, &GmailDraftsUpdateCmd{}, []string{
+			"d1", "--to", "a@example.com", "--subject", "Re: hi", "--body", "Hello", "--thread-id", "t1",
+		}, ctx, flags); runErr != nil {
+			t.Fatalf("execute: %v", runErr)
+		}
+	})
+
+	if posted.Message == nil {
+		t.Fatal("no draft posted")
+	}
+	if posted.Message.ThreadId != "t1" {
+		t.Fatalf("expected caller thread t1 to override existing te, got %q", posted.Message.ThreadId)
+	}
+	raw, decErr := base64.RawURLEncoding.DecodeString(posted.Message.Raw)
+	if decErr != nil {
+		t.Fatalf("decode raw: %v", decErr)
+	}
+	if !strings.Contains(string(raw), "In-Reply-To: <latest@id>") {
+		t.Fatalf("In-Reply-To not anchored to caller thread's latest message:\n%s", string(raw))
+	}
+}