Back to Details

gmail-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Gmail Skill - Email & Contacts Access

Gmail Skill - 邮件与联系人访问

Read, search, and send Gmail emails. Access Google contacts.
读取、搜索和发送Gmail邮件，访问Google联系人。

CRITICAL: Email Sending Confirmation Required

重要提醒：发送邮件必须确认

Before sending ANY email, you MUST get explicit user confirmation.
When the user asks to send an email:
  1. First, show them the complete email details:
    • From (which account)
    • To
    • CC/BCC (if any)
    • Subject
    • Full body text
  2. Ask: "Do you want me to send this email?"
  3. ONLY run the send command AFTER the user explicitly confirms (e.g., "yes", "send it", "go ahead")
  4. NEVER send an email without this confirmation, even if the user asked you to send it initially
This applies even when:
  • The user says "send an email to X"
  • You are in "dangerously skip permissions" mode
  • The user seems to be in a hurry
Always confirm first. No exceptions.
在发送任何邮件之前，你必须获得用户的明确确认。
当用户要求发送邮件时：
  1. 首先，向他们展示完整的邮件详情：
    • 发件人（哪个账户）
    • 收件人
    • 抄送/密送（如有）
    • 主题
    • 完整正文内容
  2. 询问：“你是否要我发送这封邮件？”
  3. 只有在用户明确确认后（例如“是”、“发送它”、“继续”），才能执行发送命令
  4. 即使用户最初要求发送邮件，也绝不要在未确认的情况下发送邮件
以下情况同样适用：
  • 用户说“给X发送一封邮件”
  • 处于“危险跳过权限”模式
  • 用户看起来很匆忙
始终先确认，无例外。

First-Time Setup (One-Time, ~2 minutes)

首次设置（仅需一次，约2分钟）

On first run, the script will guide you through setup. You need to create a Google Cloud OAuth client once:
  1. Go to Google Cloud Console
  2. Create a project (or select existing)
  3. Enable Gmail API and People API (APIs & Services → Library)
  4. Configure OAuth consent screen:
    • User Type: External
    • App name: Gmail Skill
    • Add yourself as test user
    • Add scopes: 
      gmail.readonly
      , 
      gmail.send
      , 
      gmail.modify
      , 
      contacts.readonly
  5. Create OAuth client ID:
    • Application type: Desktop app
    • Download JSON → save as 
      ~/.claude/skills/gmail-skill/credentials.json
Then just run any command - browser opens, you approve, done. Works for all your accounts.
Note: If you previously used gmail-reader, you'll need to re-authenticate to grant the new 
gmail.send
scope.
首次运行时，脚本会引导你完成设置。你需要创建一个Google Cloud OAuth客户端：
  1. 访问 Google Cloud Console
  2. 创建一个项目（或选择现有项目）
  3. 启用Gmail API和People API（API与服务 → 库）
  4. 配置OAuth同意屏幕：
    • 用户类型：外部
    • 应用名称：Gmail Skill
    • 添加自己为测试用户
    • 添加权限范围：
      gmail.readonly
      , 
      gmail.send
      , 
      gmail.modify
      , 
      contacts.readonly
  5. 创建OAuth客户端ID：
    • 应用类型：桌面应用
    • 下载JSON → 保存为 
      ~/.claude/skills/gmail-skill/credentials.json
然后只需运行任意命令 - 浏览器会打开，你授权后即可完成设置。适用于你所有的账户。
注意： 如果你之前使用过gmail-reader，需要重新授权以获取新的
gmail.send
权限范围。

Commands

命令

Search Emails

搜索邮件

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "query" [--max-results N] [--account EMAIL]
Query examples:
  • from:john@example.com
    - from specific sender
  • subject:meeting after:2026/01/01
    - subject + date
  • has:attachment filename:pdf
    - with PDF attachments
  • is:unread
    - unread emails
  • "exact phrase"
    - exact match
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "query" [--max-results N] [--account EMAIL]
查询示例：
  • from:john@example.com
    - 来自特定发件人
  • subject:meeting after:2026/01/01
    - 主题+日期
  • has:attachment filename:pdf
    - 包含PDF附件
  • is:unread
    - 未读邮件
  • "exact phrase"
    - 精确匹配

Read Email

读取邮件

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py read EMAIL_ID [--account EMAIL]
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py read EMAIL_ID [--account EMAIL]

List Recent Emails

列出最近邮件

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list [--max-results N] [--label LABEL] [--account EMAIL]
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list [--max-results N] [--label LABEL] [--account EMAIL]

Send Email (Requires Confirmation)

发送邮件（需要确认）

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send --to EMAIL --subject "Subject" --body "Body text" [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]
Required arguments:
  • --to
    / 
    -t
    - Recipient email address
  • --subject
    / 
    -s
    - Email subject line
  • --body
    / 
    -b
    - Email body text
Optional arguments:
  • --cc
    - CC recipients (comma-separated)
  • --bcc
    - BCC recipients (comma-separated)
  • --account
    / 
    -a
    - Send from specific account
Example:
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "recipient@example.com" \
  --subject "Meeting Tomorrow" \
  --body "Hi, just confirming our meeting at 2pm tomorrow." \
  --account work@company.com
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send --to EMAIL --subject "Subject" --body "Body text" [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]
必填参数：
  • --to
    / 
    -t
    - 收件人邮箱地址
  • --subject
    / 
    -s
    - 邮件主题
  • --body
    / 
    -b
    - 邮件正文
可选参数：
  • --cc
    - 抄送收件人（逗号分隔）
  • --bcc
    - 密送收件人（逗号分隔）
  • --account
    / 
    -a
    - 使用特定账户发送
示例：
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "recipient@example.com" \
  --subject "Meeting Tomorrow" \
  --body "Hi, just confirming our meeting at 2pm tomorrow." \
  --account work@company.com

Mark as Read

标记为已读

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read EMAIL_ID [--account EMAIL]
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read EMAIL_ID [--account EMAIL]

Mark as Unread

标记为未读

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-unread EMAIL_ID [--account EMAIL]
Both mark-read and mark-unread support multiple IDs (comma-separated):
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account user@gmail.com
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-unread EMAIL_ID [--account EMAIL]
标记已读和标记未读都支持多个ID（逗号分隔）：
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account user@gmail.com

Mark Done (Archive)

标记为已处理（归档）

Archives email(s) by removing from inbox. Equivalent to Gmail's 'e' keyboard shortcut.
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-done EMAIL_ID [--account EMAIL]
通过从收件箱移除来归档邮件。相当于Gmail的'e'键盘快捷键。
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-done EMAIL_ID [--account EMAIL]

Unarchive

取消归档

Moves email(s) back to inbox (undo archive).
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py unarchive EMAIL_ID [--account EMAIL]
将邮件移回收件箱（撤销归档）。
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py unarchive EMAIL_ID [--account EMAIL]

Star / Unstar

加星标 / 取消星标

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py star EMAIL_ID [--account EMAIL]
python3 ~/.claude/skills/gmail-skill/gmail_skill.py unstar EMAIL_ID [--account EMAIL]
All label commands support multiple IDs (comma-separated):
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py star "id1,id2,id3" --account user@gmail.com
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py star EMAIL_ID [--account EMAIL]
python3 ~/.claude/skills/gmail-skill/gmail_skill.py unstar EMAIL_ID [--account EMAIL]
所有标签命令都支持多个ID（逗号分隔）：
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py star "id1,id2,id3" --account user@gmail.com

Create Draft

创建草稿

Creates a draft email. Use 
--reply-to-id
when replying to an existing email to ensure proper threading in email clients like Superhuman.
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft --to EMAIL --subject "Subject" --body "Body text" [--reply-to-id EMAIL_ID] [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]
Required arguments:
  • --to
    / 
    -t
    - Recipient email address
  • --subject
    / 
    -s
    - Email subject line
  • --body
    / 
    -b
    - Email body text
Optional arguments:
  • --reply-to-id
    / 
    -r
    - Message ID to reply to (adds proper In-Reply-To and References headers for threading)
  • --cc
    - CC recipients (comma-separated)
  • --bcc
    - BCC recipients (comma-separated)
  • --account
    / 
    -a
    - Create draft in specific account
Example (new email):
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "recipient@example.com" \
  --subject "Draft for Review" \
  --body "Here's my draft message."
Example (reply to existing email):
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "sender@example.com" \
  --subject "Re: Original Subject" \
  --body "Thanks for your email..." \
  --reply-to-id 19b99b3127793843 \
  --account work@company.com
创建邮件草稿。回复现有邮件时使用
--reply-to-id
，以确保在Superhuman等邮件客户端中正确显示对话线程。
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft --to EMAIL --subject "Subject" --body "Body text" [--reply-to-id EMAIL_ID] [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]
必填参数：
  • --to
    / 
    -t
    - 收件人邮箱地址
  • --subject
    / 
    -s
    - 邮件主题
  • --body
    / 
    -b
    - 邮件正文
可选参数：
  • --reply-to-id
    / 
    -r
    - 回复的消息ID（添加正确的In-Reply-To和References头以支持对话线程）
  • --cc
    - 抄送收件人（逗号分隔）
  • --bcc
    - 密送收件人（逗号分隔）
  • --account
    / 
    -a
    - 在特定账户中创建草稿
示例（新邮件）：
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "recipient@example.com" \
  --subject "Draft for Review" \
  --body "Here's my draft message."
示例（回复现有邮件）：
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "sender@example.com" \
  --subject "Re: Original Subject" \
  --body "Thanks for your email..." \
  --reply-to-id 19b99b3127793843 \
  --account work@company.com

List Labels

列出标签

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py labels [--account EMAIL]
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py labels [--account EMAIL]

List Contacts

列出联系人

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py contacts [--max-results N] [--account EMAIL]
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py contacts [--max-results N] [--account EMAIL]

Search Contacts

搜索联系人

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "query" [--account EMAIL]
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "query" [--account EMAIL]

Manage Accounts

管理账户

bash
undefined
bash
undefined

List all authenticated accounts

列出所有已认证账户

python3 ~/.claude/skills/gmail-skill/gmail_skill.py accounts
python3 ~/.claude/skills/gmail-skill/gmail_skill.py accounts

Remove an account

移除账户

python3 ~/.claude/skills/gmail-skill/gmail_skill.py logout --account user@gmail.com
undefined
python3 ~/.claude/skills/gmail-skill/gmail_skill.py logout --account user@gmail.com
undefined

Multi-Account Support

多账户支持

Add accounts by using 
--account
with a new email - browser opens for that account:
bash
undefined
通过使用
--account
参数并指定新邮箱来添加账户 - 会打开浏览器进行该账户的授权：
bash
undefined

First account (auto-authenticates)

第一个账户（自动认证）

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list

Add work account

添加工作账户

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com

Add personal account

添加个人账户

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account personal@gmail.com
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account personal@gmail.com

Use specific account

使用特定账户

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account work@company.com

Tokens are stored per-account in `~/.claude/skills/gmail-skill/tokens/`
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account work@company.com

令牌按账户存储在 `~/.claude/skills/gmail-skill/tokens/`

Examples

示例

Find unread emails from this week

查找本周未读邮件

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "is:unread after:2026/01/01"
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "is:unread after:2026/01/01"

Read a specific email

读取特定邮件

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py read 18d5a3b2c1f4e5d6
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py read 18d5a3b2c1f4e5d6

Send a quick email

快速发送邮件

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "friend@example.com" \
  --subject "Hello!" \
  --body "Just wanted to say hi."
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "friend@example.com" \
  --subject "Hello!" \
  --body "Just wanted to say hi."

Find someone's contact info

查找某人的联系人信息

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "John Smith"
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "John Smith"

Check work email from personal machine

在个人设备上查看工作邮件

bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com --max-results 5
bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com --max-results 5

Output

输出

All commands output JSON for easy parsing.
所有命令均输出JSON格式，便于解析。

Requirements

要求

  • Python 3.9+
  • pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client requests
  • Python 3.9+
  • pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client requests

Security Notes

安全说明

  • Send confirmation required - Claude must always confirm with the user before sending emails
  • Tokens stored locally in 
    ~/.claude/skills/gmail-skill/tokens/
  • Revoke access anytime: https://myaccount.google.com/permissions
  • Apps in "testing" mode may require re-auth every 7 days (publish app to avoid)
  • 发送必须确认 - Claude必须始终在发送邮件前获得用户确认
  • 令牌本地存储在 
    ~/.claude/skills/gmail-skill/tokens/
  • 随时撤销访问权限：https://myaccount.google.com/permissions
  • 处于“测试”模式的应用可能需要每7天重新授权（发布应用可避免此问题）