gmail-access

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gmail Access

Gmail 访问

Read and search Gmail programmatically via Claude Code CLI.

通过Claude Code CLI以编程方式读取和搜索Gmail。

MANDATORY PREFLIGHT (Execute Before Any Gmail Operation)

必做前置检查（执行任何Gmail操作前完成）

CRITICAL: You MUST complete this preflight checklist before running any Gmail commands. Do NOT skip steps.

重要提示：在运行任何Gmail命令前，你必须完成此前置检查清单。请勿跳过任何步骤。

Step 1: Check CLI Binary Exists

步骤1：检查CLI二进制文件是否存在

bash

ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-tools/skills/gmail-access/scripts/gmail" 2>/dev/null || echo "BINARY_NOT_FOUND"

If BINARY_NOT_FOUND: Build it first:

bash

cd ~/.claude/plugins/marketplaces/cc-skills/plugins/gmail-tools/skills/gmail-access/scripts && bun install && bun run build

bash

ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-tools/skills/gmail-access/scripts/gmail" 2>/dev/null || echo "BINARY_NOT_FOUND"

如果返回BINARY_NOT_FOUND：先进行构建：

bash

cd ~/.claude/plugins/marketplaces/cc-skills/plugins/gmail-tools/skills/gmail-access/scripts && bun install && bun run build

Step 2: Check GMAIL_OP_UUID Environment Variable

步骤2：检查GMAIL_OP_UUID环境变量

bash

echo "GMAIL_OP_UUID: ${GMAIL_OP_UUID:-NOT_SET}"

If NOT_SET: You MUST run the Setup Flow below. Do NOT proceed to Gmail commands.

bash

echo "GMAIL_OP_UUID: ${GMAIL_OP_UUID:-NOT_SET}"

如果返回NOT_SET：你必须执行下方的设置流程。请勿继续执行Gmail命令。

Step 2.5: Verify Account Context (CRITICAL)

步骤2.5：验证账户上下文（重要）

ALWAYS verify you're accessing the correct email account for the current project.

bash

undefined

请始终确认你正在访问当前项目对应的正确邮箱账户。

bash

undefined

Show current project context

echo "=== Gmail Account Context ===" echo "Working directory: $(pwd)" echo "GMAIL_OP_UUID: ${GMAIL_OP_UUID}"

Check where GMAIL_OP_UUID is defined (mise hierarchy)

echo "" echo "=== mise Config Source ===" grep -l "GMAIL_OP_UUID" .mise.local.toml .mise.toml ~/.config/mise/config.toml 2>/dev/null || echo "Not found in standard locations"

Get the email address from 1Password for this UUID

echo "" echo "=== Email Account for this UUID ===" op item get "${GMAIL_OP_UUID}" --fields label=email 2>/dev/null || op item get "${GMAIL_OP_UUID}" --format json 2>/dev/null | jq -r '.title'


**STOP and confirm with user** before proceeding:

- Display the email account that will be accessed
- Verify this matches the project's intended email (check `RECRUITER_EMAIL` or similar project-specific vars)
- If mismatch, inform user and do NOT proceed

**Example verification:**

```bash

echo "" echo "=== Email Account for this UUID ===" op item get "${GMAIL_OP_UUID}" --fields label=email 2>/dev/null || op item get "${GMAIL_OP_UUID}" --format json 2>/dev/null | jq -r '.title'


**继续前请先与用户确认**：

- 展示即将访问的邮箱账户
- 验证该账户是否与项目预期的邮箱匹配（检查`RECRUITER_EMAIL`或其他项目特定变量）
- 如果不匹配，告知用户并停止操作

**验证示例：**

```bash

Compare configured email with project expectation

PROJECT_EMAIL="${RECRUITER_EMAIL:-$(grep -m1 'email' .mise.toml 2>/dev/null | cut -d'"' -f2)}" echo "Project expects: ${PROJECT_EMAIL:-'(not specified)'}" echo "Gmail UUID maps to: $(op item get "${GMAIL_OP_UUID}" --fields label=email 2>/dev/null)"

undefined

undefined

Step 3: Verify 1Password Authentication

步骤3：验证1Password身份认证

bash

op account list 2>&1 | head -3

If error or not signed in: Inform user to run

op signin

first.

bash

op account list 2>&1 | head -3

如果出现错误或未登录：告知用户先运行

op signin

。

Setup Flow (When GMAIL_OP_UUID is NOT_SET)

设置流程（当GMAIL_OP_UUID为NOT_SET时）

Follow these steps IN ORDER. Use AskUserQuestion at decision points.

请按顺序执行以下步骤。在决策点使用AskUserQuestion。

Setup Step 1: Check 1Password CLI

设置步骤1：检查1Password CLI

bash

command -v op && echo "OP_CLI_INSTALLED" || echo "OP_CLI_MISSING"

If OP_CLI_MISSING: Stop and inform user:

1Password CLI is required. Install with:
brew install 1password-cli

bash

command -v op && echo "OP_CLI_INSTALLED" || echo "OP_CLI_MISSING"

如果返回OP_CLI_MISSING：停止操作并告知用户：

需要安装1Password CLI。安装命令：
brew install 1password-cli

Setup Step 2: Discover Gmail OAuth Items in 1Password

设置步骤2：在1Password中查找Gmail OAuth项

bash

op item list --vault Employee --format json 2>/dev/null | jq -r '.[] | select(.title | test("gmail|oauth|google"; "i")) | "\(.id)\t\(.title)"'

Parse the output and proceed based on results:

bash

op item list --vault Employee --format json 2>/dev/null | jq -r '.[] | select(.title | test("gmail|oauth|google"; "i")) | "\(.id)\t\(.title)"'

解析输出结果并根据结果继续操作：

Setup Step 3: User Selects OAuth Credentials

设置步骤3：用户选择OAuth凭据

If items found, use AskUserQuestion with discovered items:

AskUserQuestion({
  questions: [{
    question: "Which 1Password item contains your Gmail OAuth credentials?",
    header: "Gmail OAuth",
    options: [
      // POPULATE FROM op item list RESULTS - example:
      { label: "Gmail API - dental-quizzes (56peh...)", description: "OAuth client in Employee vault" },
      { label: "Gmail API - personal (abc12...)", description: "Personal OAuth client" },
    ],
    multiSelect: false
  }]
})

If NO items found, use AskUserQuestion to guide setup:

AskUserQuestion({
  questions: [{
    question: "No Gmail OAuth credentials found in 1Password. How would you like to proceed?",
    header: "Setup",
    options: [
      { label: "Create new OAuth credentials (Recommended)", description: "I'll guide you through Google Cloud Console setup" },
      { label: "I have credentials elsewhere", description: "Help me add them to 1Password" },
      { label: "Skip for now", description: "I'll set this up later" }
    ],
    multiSelect: false
  }]
})

If "Create new OAuth credentials": Read and present references/gmail-api-setup.md
If "I have credentials elsewhere": Guide user to add to 1Password with required fields
If "Skip for now": Inform user the skill won't work until configured

如果找到相关项，使用AskUserQuestion展示发现的项：

AskUserQuestion({
  questions: [{
    question: "哪个1Password项包含你的Gmail OAuth凭据？",
    header: "Gmail OAuth",
    options: [
      // POPULATE FROM op item list RESULTS - example:
      { label: "Gmail API - dental-quizzes (56peh...)", description: "OAuth client in Employee vault" },
      { label: "Gmail API - personal (abc12...)", description: "Personal OAuth client" },
    ],
    multiSelect: false
  }]
})

如果未找到相关项，使用AskUserQuestion引导设置：

AskUserQuestion({
  questions: [{
    question: "在1Password中未找到Gmail OAuth凭据。你希望如何继续？",
    header: "设置",
    options: [
      { label: "创建新的OAuth凭据（推荐）", description: "我将引导你完成Google Cloud Console设置" },
      { label: "我在其他地方已有凭据", description: "帮助我将其添加到1Password" },
      { label: "暂时跳过", description: "我稍后再进行设置" }
    ],
    multiSelect: false
  }]
})

如果选择“创建新的OAuth凭据”：读取并展示references/gmail-api-setup.md
如果选择“我在其他地方已有凭据”：引导用户将凭据添加到1Password并填写必填字段
如果选择“暂时跳过”：告知用户在完成配置前该技能无法使用

Setup Step 4: Confirm mise Configuration

设置步骤4：确认mise配置

After user selects an item (with UUID), use AskUserQuestion:

AskUserQuestion({
  questions: [{
    question: "Add GMAIL_OP_UUID to .mise.local.toml in current project?",
    header: "Configure",
    options: [
      { label: "Yes, add to .mise.local.toml (Recommended)", description: "Creates/updates gitignored config file" },
      { label: "Show me the config only", description: "I'll add it manually" }
    ],
    multiSelect: false
  }]
})

If "Yes, add to .mise.local.toml":

Check if
```
.mise.local.toml
```
exists
If exists, append
```
GMAIL_OP_UUID
```
to
```
[env]
```
section
If not exists, create with:

toml

[env]
GMAIL_OP_UUID = "<selected-uuid>"

Verify
```
.mise.local.toml
```
is in
```
.gitignore
```

If "Show me the config only": Output the TOML for user to add manually.

用户选择项（含UUID）后，使用AskUserQuestion：

AskUserQuestion({
  questions: [{
    question: "将GMAIL_OP_UUID添加到当前项目的.mise.local.toml中？",
    header: "配置",
    options: [
      { label: "是，添加到.mise.local.toml（推荐）", description: "创建/更新被Git忽略的配置文件" },
      { label: "仅展示配置内容", description: "我将手动添加" }
    ],
    multiSelect: false
  }]
})

如果选择“是，添加到.mise.local.toml”：

检查
```
.mise.local.toml
```
是否存在
如果存在，将
```
GMAIL_OP_UUID
```
追加到
```
[env]
```
节
如果不存在，创建以下内容：

toml

[env]
GMAIL_OP_UUID = "<selected-uuid>"

验证
```
.mise.local.toml
```
是否在
```
.gitignore
```
中

如果选择“仅展示配置内容”：输出TOML内容供用户手动添加。

Setup Step 5: Reload and Verify

设置步骤5：重新加载并验证

bash

mise trust 2>/dev/null || true
cd . && echo "GMAIL_OP_UUID after reload: ${GMAIL_OP_UUID:-NOT_SET}"

If still NOT_SET: Inform user to restart their shell or run

source ~/.zshrc

bash

mise trust 2>/dev/null || true
cd . && echo "GMAIL_OP_UUID after reload: ${GMAIL_OP_UUID:-NOT_SET}"

如果仍然返回NOT_SET：告知用户重启Shell或运行

source ~/.zshrc

。

Setup Step 6: Test Connection

设置步骤6：测试连接

bash

GMAIL_OP_UUID="${GMAIL_OP_UUID}" $HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-tools/skills/gmail-access/scripts/gmail list -n 1

If OAuth prompt appears: This is expected on first run. Browser will open for Google consent.

bash

GMAIL_OP_UUID="${GMAIL_OP_UUID}" $HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-tools/skills/gmail-access/scripts/gmail list -n 1

如果出现OAuth提示：这是首次运行的正常现象。浏览器将打开以获取Google授权。

Gmail Commands (Only After Preflight Passes)

Gmail命令（仅当前置检查通过后执行）

bash

GMAIL_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-tools/skills/gmail-access/scripts/gmail"

bash

GMAIL_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-tools/skills/gmail-access/scripts/gmail"

List recent emails

$GMAIL_CLI list -n 10

Search emails

$GMAIL_CLI search "from:someone@example.com" -n 20

Search with date range

$GMAIL_CLI search "from:phoebe after:2026/01/27" -n 10

Read specific email with full body

$GMAIL_CLI read <message_id>

Export to JSON

$GMAIL_CLI export -q "label:inbox" -o emails.json -n 100

JSON output (for parsing)

$GMAIL_CLI list -n 10 --json

Create a draft email

$GMAIL_CLI draft --to "user@example.com" --subject "Hello" --body "Message body"

Create a draft reply (threads into existing conversation)

$GMAIL_CLI draft --to "user@example.com" --subject "Re: Hello" --body "Reply text" --reply-to <message_id>

undefined

$GMAIL_CLI draft --to "user@example.com" --subject "Re: Hello" --body "Reply text" --reply-to <message_id>

undefined

Creating Draft Emails

创建草稿邮件

The

draft

command creates emails in your Gmail Drafts folder for review before sending.

Required options:

```
--to
```
- Recipient email address
```
--subject
```
- Email subject line
```
--body
```
- Email body text

Optional:

```
--reply-to
```
- Message ID to reply to (creates threaded reply with proper headers)
```
--json
```
- Output draft details as JSON

Example: Create reply drafts from conversation:

bash

undefined

draft

命令会在你的Gmail草稿文件夹中创建邮件，供发送前审核。

必填选项：

```
--to
```
- 收件人邮箱地址
```
--subject
```
- 邮件主题
```
--body
```
- 邮件正文

可选选项：

```
--reply-to
```
- 要回复的消息ID（创建带正确头信息的线程化回复）
```
--json
```
- 以JSON格式输出草稿详情

示例：从对话中创建回复草稿：

bash

undefined

1. Find the message to reply to

1. 找到要回复的消息

$GMAIL_CLI search "from:someone@example.com subject:meeting" -n 5 --json

2. Create draft reply using message ID

2. 使用消息ID创建回复草稿

$GMAIL_CLI draft
--to "someone@example.com"
--subject "Re: Meeting tomorrow"
--body "Thanks for the update. I'll be there at 2pm."
--reply-to "19c1e6a97124aed8"

3. Review drafts in Gmail

3. 在Gmail中查看草稿

Open: https://mail.google.com/mail/u/0/#drafts

打开: https://mail.google.com/mail/u/0/#drafts


**Note:** After creating drafts, users need to re-authenticate if they previously only had read access. The CLI will prompt for OAuth consent to add the `gmail.compose` scope.


**注意：** 创建草稿后，如果用户之前仅有读取权限，需要重新进行身份认证。CLI将提示获取OAuth授权以添加`gmail.compose`权限范围。

Gmail Search Syntax

Gmail搜索语法

Query	Description
`from:sender@example.com`	From specific sender
`to:recipient@example.com`	To specific recipient
`subject:keyword`	Subject contains keyword
`after:2026/01/01`	After date
`before:2026/02/01`	Before date
`label:inbox`	Has label
`is:unread`	Unread emails
`has:attachment`	Has attachment

Reference: https://support.google.com/mail/answer/7190

查询语句	描述
`from:sender@example.com`	来自特定发件人
`to:recipient@example.com`	发送给特定收件人
`subject:keyword`	主题包含关键词
`after:2026/01/01`	晚于指定日期
`before:2026/02/01`	早于指定日期
`label:inbox`	包含指定标签
`is:unread`	未读邮件
`has:attachment`	包含附件

参考链接：https://support.google.com/mail/answer/7190

Environment Variables

环境变量

Variable	Required	Description
`GMAIL_OP_UUID`	Yes	1Password item UUID for OAuth credentials
`GMAIL_OP_VAULT`	No	1Password vault (default: Employee)

变量名	是否必填	描述
`GMAIL_OP_UUID`	是	用于OAuth凭据的1Password项UUID
`GMAIL_OP_VAULT`	否	1Password保险箱（默认值：Employee）

Token Storage

令牌存储

OAuth tokens stored at:

~/.claude/tools/gmail-tokens/<uuid>.json

Central location (not in plugin, not in project)
Organized by 1Password UUID (supports multi-account)
Created with chmod 600

OAuth令牌存储位置：

~/.claude/tools/gmail-tokens/<uuid>.json

集中存储（不在插件或项目中）
按1Password UUID分类（支持多账户）
创建时权限为chmod 600

References

参考文档

mise-templates.md - Complete mise configuration templates
mise-setup.md - Step-by-step mise setup guide
gmail-api-setup.md - Google Cloud OAuth setup guide

mise-templates.md - 完整的mise配置模板
mise-setup.md - 分步mise设置指南
gmail-api-setup.md - Google Cloud OAuth设置指南

Post-Change Checklist

变更后检查清单

YAML frontmatter valid (no colons in description)
Trigger keywords current
Path patterns use $HOME not hardcoded paths
References exist and are linked

YAML前置元数据有效（描述中无冒号）
触发关键词为最新
路径模式使用$HOME而非硬编码路径
参考文档存在且链接有效