Tool: Gmail

This directory documents the Gmail tool adapter — the set of capabilities the skills use when the adopting project declares Gmail as a backend in its mail-source configuration.

A project opts into this tool by listing it in its manifest under Mail sources. For the adopting project see ../../<project-config>/project.md.

Gmail's full capability set per the backend contract: list_recent_threads, read_thread, list_drafts, list_sent_since, create_draft, thread_url. It is therefore the only in-tree adapter that supports drafting; an adopter that designates a read-only primary (e.g. Ponymail, mbox) typically also lists Gmail as preferred for create_draft, list_drafts.

What this tool provides

The skills use Gmail for four capabilities. Each has its own reference file in this directory:

Capability	File	What it covers
MCP operations	operations.md	The mcp__claude_ai_Gmail__* tool catalogue (search, read, draft, list) + the no-update / no-delete limitation
Drafting backends	draft-backends.md	The two drafting backends (claude.ai Gmail MCP — default and recommended, with thread attachment via replyToMessageId; OAuth + curl — opt-in for bulk operations and threadId-keyed drafts), why both exist, and the tools.gmail.draft_backend config knob
Threading	threading.md	The "always attach the draft to the inbound thread when possible" rule — how drafts stay on the inbound thread across reporter replies, ASF-security relays, PMC credit questions, follow-ups
ASF-security-relay drafting	asf-relay.md	Special-case drafting rules when the inbound report is relayed by the ASF security team rather than sent by the external reporter directly
Search queries	search-queries.md	Gmail search-operator cheat-sheet + skill-specific query templates (candidate-listing, reporter-thread lookup, CVE-review comments)

Related, adjacent tool:

Capability	File	What it covers
ASF PonyMail archive lookups	ponymail-archive.md	URL-construction pattern for the ASF's lists.apache.org archive (used by security-issue-sync to scan the public users@ archive for the advisory URL, and by security-issue-import to resolve a pastable thread URL for the private security@ list)

Why this is its own tool

Gmail is the security team's inbox for the private security@<project>.apache.org mailing list and the draft queue for every outbound reporter reply the skills compose. Gmail's draft capability is load-bearing and cannot be swapped — this directory stays in every project's toolchain because PonyMail MCP, the alternative read path documented at ../ponymail/tool.md, is read-only and cannot compose reporter replies.

Role when PonyMail MCP is opted into. When a user sets tools.ponymail.enabled: true in their .apache-magpie-overrides/user.md and authenticates the MCP, PonyMail becomes the primary read backend for archive queries (reporter-thread lookups, reviewer-comment searches, users@ / dev@ archive scans, prior-rejection precedents). Gmail stays as the fallback read path — used when a specific list is outside the user's tools.ponymail.private_lists allowlist, when PonyMail returns an error, or when inbox latency matters for just-arrived messages. Gmail remains the only backend for draft composition regardless. When the user has not opted into PonyMail MCP, Gmail is the sole read backend and the skills run exactly as before.

When to replace this tool with another

A project that runs on a different mail stack can swap this directory for a sibling tools/<name>/ that provides equivalent capabilities against its own backend (Fastmail, Microsoft Graph, Mailgun, a ponymail-mcp OAuth flow, …). The contract the generic skills rely on is:

1. Search — given a query and a time window, return matching thread IDs.
2. Read — given a thread ID, return the full message history.
3. Draft — given a thread ID, create an unsent reply on the inbound thread with thread attachment (the default claude_ai_mcp backend resolves the thread's latest message ID and attaches via replyToMessageId; the opt-in oauth_curl backend attaches by threadId); fall back to a subject-matched draft (Re: <root subject> + In-Reply-To / References headers so the recipient's client still threads it) when the thread cannot be resolved. The two backends available today are documented in draft-backends.md.
4. List drafts — so stale drafts can be detected before the skills forward-flag them in every new sync comment.

The threading semantics — "attach the draft to the inbound thread when possible; fall back to same-subject matching when not, never fabricate a new subject" — are non-negotiable regardless of backend; see threading.md.

Confidentiality

Gmail drafts created by the skills land in the user's personal Gmail account and are visible only to that user until sent. Never send — the skills only create drafts; a human review-and-send step is required for every outbound message. Confidentiality rules in ../../AGENTS.md still bind the draft content: status updates to the reporter may reference the private tracker URL (reporter is on the private thread), but any message destined for a mailing list outside the security circle must be scrubbed.