Feature: helper to resolve Gmail web URL (sync ID, FMfcgz...) to an API thread

Aberta
#790 0 comentários 3 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
45/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Pouca atividade
Stack de tecnologia
rust
Domínio
api, cli

Direção de pesquisa

Begin by locating the existing +triage and +watch helpers and the Gmail thread-listing command they abstract. Define how URL parsing, label filtering, hint options, disambiguation, and JSON output should fit those patterns; completion means a URL or hint resolves to API thread IDs or presents usable matches, with the README and gws-gmail SKILL.md documenting sync IDs.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

Problem

Gmail's web UI URLs no longer expose the API thread ID. The address bar now shows opaque "sync IDs" prefixed with FMfcgz...:

https://mail.google.com/mail/u/0/#inbox/FMfcgzQgLjNPlfJCVRfnNkPGkLhWClCW

Passing this directly to the API returns Invalid id value:

$ gws gmail users threads get --params '{"userId":"me","id":"FMfcgzQgLjNPlfJCVRfnNkPGkLhWClCW"}'
{
  "error": {
    "code": 400,
    "message": "Invalid id value",
    "reason": "invalidArgument"
  }
}

The Gmail API only accepts hex thread IDs like 19e1acd465710c93, which the new Gmail UI never shows to the user. So the most natural input an agent or human has for "this email" — the URL they can copy from the browser — is unusable with gws.

Why a client-side conversion is not possible

I checked whether the sync ID can be decoded into the hex thread ID locally. Decoded as base64url, it is 24 bytes:

FMfcgzQgLjNPlfJCVRfnNkPGkLhWClCW
  ↓
14 C7 DC 83 34 | 20 2E 33 4F 95 F2 42 55 17 E7 36 43 C6 90 B8 56 0A 50 96
└── magic ────┘└──────── 19 bytes opaque payload ────────┘
  • The first 5 bytes are a constant scheme tag (every URL starts with FMfcgz).
  • The remaining 19 bytes contain no recognizable substring of the corresponding hex thread ID. Length and entropy suggest a ciphertext + authentication tag, and sync IDs differ across accounts for the same thread — i.e. wrapped with a per-account server-side key.

This matches the upstream consensus that "the newer 'sync' style IDs that appear in the browser's address bar don't yet work with the Gmail API". A deterministic offline conversion is not on the table.

Real-world use case

When an agent (or a human) wants gws to act on a specific email, the most natural reference is the Gmail web URL they're currently looking at. Today that requires:

  1. Realize the URL ID won't work.
  2. Run gws gmail users threads list ....
  3. Eyeball snippets to guess which thread is the right one.
  4. Copy the hex id into the next command.

Step 3 is unreliable when the inbox is busy or when the email isn't recent.

Proposed solution

A helper that does the fuzzy lookup explicitly, taking either a URL or a free-form hint:

# Resolve from a Gmail web URL by listing candidates around its likely time window
gws gmail +find --url 'https://mail.google.com/mail/u/0/#inbox/FMfcgz...'

# Or by hint (subject / sender / time window)
gws gmail +find "Supabase monthly"
gws gmail +find --from [email protected] --since 24h
gws gmail +find --subject "ChatGPT" --label INBOX

The helper would:

  1. Parse the URL, extract the label segment (#inbox, #sent, #label/Foo, …) and use it as a labelIds filter. The sync ID itself is treated as opaque context, not decoded.
  2. Call users.threads.list with the matching label and a reasonable maxResults (e.g. 50).
  3. If --subject/--from/--since narrows it to one thread, return the hex id (and snippet) ready to pipe into gws gmail users threads get.
  4. Otherwise print a numbered list with sender, subject, date, and snippet — same shape as +triage — so the user/agent can disambiguate without re-running the full API call.

JSON output for agents:

{
  "matches": [
    {
      "id": "19e1acd465710c93",
      "threadId": "19e1acd465710c93",
      "from": "Supabase <[email protected]>",
      "subject": "Supabase Monthly — April",
      "date": "2026-05-11T08:14:00Z",
      "snippet": "Everything that happened in the last month at Supabase ..."
    }
  ],
  "source": {
    "url": "https://mail.google.com/mail/u/0/#inbox/FMfcgz...",
    "label": "INBOX"
  }
}

This stays within the public API surface, requires no decryption, and is consistent with how other + helpers (+triage, +watch) abstract listing operations.

Alternative: documentation only

At minimum, a one-sentence note in the README and gws-gmail SKILL.md that Gmail web URL IDs (FMfcgz...) are not valid API IDs would save users from the confusing Invalid id value error and a round of debugging. The current SKILL examples implicitly assume the user already has a hex ID, which is increasingly hard to obtain from a browser.

Environment

  • gws 0.22.5 (installed via npm install -g @googleworkspace/cli)
  • Node 24.13
  • Windows 11
Linguagem predominante
Rust
Estrelas
32.3k
Forks
2k
Merge médio
16h 3min
PRs com merge (30d)
1

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de googleworkspace/cli

Todas as issues de googleworkspace/cli

Issues semelhantes

Mais issues de Rust

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.