docs(gmail): clarify Gmail web URL sync IDs

.changeset/gmail-web-url-sync-ids.md

@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Document that Gmail web URL sync IDs are not Gmail API message or thread IDs.

README.md

@@ -341,6 +341,11 @@ gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"
 # Reply to a message
 gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"
 
+# Gmail web URL IDs such as FMfcgz... are browser sync IDs, not API IDs.
+# Search/list first when you need the API message or thread ID.
+gws gmail users messages list \
+  --params '{"userId":"me","q":"from:alice@example.com subject:\"Quarterly report\"","maxResults":10}'
+
 # Append a row to a spreadsheet
 gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"
 

skills/gws-gmail-read/SKILL.md

@@ -45,6 +45,9 @@ gws gmail +read --id 18f1a2b3c4d --format json | jq '.body'
 
 - Converts HTML-only messages to plain text automatically.
 - Handles multipart/alternative and base64 decoding.
+- The `--id` value must be a Gmail API message ID. Opaque Gmail web URL IDs
+  such as `FMfcgz...` are browser sync IDs and are not accepted by the Gmail
+  API; search or list messages first when you only have a browser URL.
 
 ## See Also
 

skills/gws-gmail/SKILL.md

@@ -59,3 +59,17 @@ gws schema gmail.<resource>.<method>
 
 Use `gws schema` output to build your `--params` and `--json` flags.
 
+## Gmail IDs
+
+Gmail API methods require API message or thread IDs, not browser URL sync IDs.
+Recent Gmail web URLs often end with opaque IDs such as `FMfcgz...`; passing
+those values to `users.messages.get` or `users.threads.get` returns
+`Invalid id value`.
+
+To act on a message you are viewing in Gmail, first locate the API ID with a
+query you can verify:
+
+```bash
+gws gmail users messages list --params '{"userId":"me","q":"from:alice@example.com subject:\"Quarterly report\"","maxResults":10}'
+gws gmail users messages get --params '{"userId":"me","id":"API_MESSAGE_ID"}'
+```