Gmail Enhanced

具备强大自动化功能的高级 Gmail 集成。

功能

1. 高级搜索

• 构建复杂查询（AND、OR、NOT）
• 日期范围筛选
• 附件筛选
• 标签筛选
• 在附件内容中搜索

2. 标签管理

• 创建、重命名、删除标签
• 嵌套标签（类文件夹结构）
• 自定义标签颜色
• 标签统计信息

3. 附件处理

• 下载附件
• 上传并发送附件
• 按类型/大小筛选附件
• 将附件提取至云存储

4. 邮件处理

• 自动对邮件分类
• 从邮件中提取数据
• 自动回复规则
• 邮件模板
• 退信检测

5. 邮件解析

• 提取结构化数据
• 解析发票、收据
• 提取联系人信息
• HTML 解析

前提条件

1. 在 Google Cloud Console 中启用 Gmail API
2. 创建 OAuth 2.0 凭据
3. 下载 credentials.json
4. 生成 tokens.json（首次运行时需完成身份验证）

配置

export GMAIL_CREDENTIALS_PATH="/path/to/credentials.json"
export GMAIL_TOKEN_PATH="/path/to/tokens.json"

或直接将凭据文件置于默认路径：

• ~/.credentials/gmail-credentials.json
• ~/.credentials/gmail-token.json

使用方法

发送邮件

from gmail_enhanced import GmailClient

gmail = GmailClient()

# 简单邮件
gmail.send(
    to="recipient@example.com",
    subject="Hello",
    body="Email content"
)

# 带附件的邮件
gmail.send(
    to="recipient@example.com",
    subject="Report",
    body="Please find the report attached",
    attachments=["report.pdf"]
)

高级搜索

# 复杂查询
results = gmail.search(
    query="from:boss@company.com",
    label="INBOX",
    after="2024/01/01",
    has_attachments=True
)

# 使用 OR 的组合查询
results = gmail.search_or([
    "subject:urgent",
    "label:important"
])

标签管理

# 创建标签
label = gmail.create_label("Projects/Work/Q1", color="#4A90E2")

# 获取标签统计信息
stats = gmail.get_label_stats("INBOX")

# 为邮件添加标签
gmail.add_labels(["Label1", "Label2"], message_ids)

附件处理

# 从搜索结果中下载附件
attachments = gmail.search_attachments(
    query="subject:invoice",
    save_dir="./downloads"
)

# 上传附件并发送
gmail.send(
    to="recipient@example.com",
    subject="File",
    attachments=["/path/to/file.pdf"]
)

自动分类

# 创建规则
gmail.add_rule(
    name="Categorize invoices",
    query="subject:invoice has:attachment",
    add_labels=["Processed/Invoices"]
)

# 执行所有规则
gmail.process_rules()

API 参考

核心方法

标签方法

附件方法

自动化方法

解析方法

邮件查询语法

基础语法：
  from:user@example.com
  to:user@example.com
  subject:keyword
  "精确短语"

时间筛选：
  after:2024/01/01
  before:2024/12/31
  older_than:7d
  newer_than:2h

标志符：
  has:attachment
  has:drive
  is:unread
  is:starred
  is:important

标签：
  label:INBOX
  label:Work

组合查询：
  from:boss AND subject:urgent
  (from:alice OR from:bob) AND is:unread

错误处理

常见错误：

• invalid_credentials：需重新完成身份验证
• rate_limit：等待后重试
• not_found：邮件 ID 无效
• permission_denied：检查 OAuth 权限范围（scopes）

所需权限范围（Scopes）

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.labels
https://www.googleapis.com/auth/gmail.modify

相关链接

• Gmail API 文档
• Google Cloud Console
• OAuth 设置指南