MAIF/melusine项目中的Gmail连接器使用指南

概述

MAIF/melusine项目中的Gmail连接器(GmailConnector)是一个强大的工具，它允许开发者直接连接到Gmail邮箱，实现邮件的自动化处理。本文将详细介绍如何配置和使用这个连接器，帮助开发者快速集成邮件处理功能到他们的工作流程中。

核心功能

GmailConnector提供了以下主要功能：

1. 邮箱连接：安全地连接到Gmail邮箱
2. 邮件检索：获取最新的邮件，支持按日期和标签过滤
3. 信息提取：从邮件中提取关键信息，包括附件
4. 邮件路由：根据分类结果将邮件移动到指定标签
5. 邮件发送：支持发送邮件功能

准备工作

1. 创建Gmail API凭证

在使用GmailConnector之前，需要先获取Google Cloud平台的API凭证：

1. 登录Google Cloud控制台
2. 创建或选择现有项目
3. 进入"APIs and Services"部分
4. 启用Gmail API服务
5. 配置OAuth同意屏幕
6. 创建OAuth客户端ID凭证
7. 下载credentials.json文件

2. 安装与初始化

首次使用时，系统会生成token.json文件，后续连接可直接使用此文件：

from melusine.connectors.gmail import GmailConnector
import logging

# 配置日志
ch = logging.StreamHandler()
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
ch.setFormatter(formatter)
connector_logger = logging.getLogger("melusine.connectors.gmail")
connector_logger.addHandler(ch)
connector_logger.setLevel(logging.INFO)

# 首次连接
connector = GmailConnector(credentials_json_path="path/to/credentials.json")

# 后续连接
connector = GmailConnector(token_json_path="path/to/token.json")

核心操作指南

1. 获取邮件

获取指定数量的最新邮件：

df = connector.get_emails(max_emails=5)

支持多种过滤条件：

# 获取过去一周内未读的INBOX邮件
df = connector.get_emails(
    max_emails=5,
    target_labels=["INBOX", "UNREAD"],
    start_date="2024/05/06",
    end_date="2024/05/12",
)

注意：日期格式必须为YYYY/MM/DD

2. 创建标签

在路由邮件前，需要确保目标标签存在：

connector.create_label("Melusine")

3. 邮件路由

批量路由

根据Melusine的分类结果批量路由邮件：

connector.route_emails(classified_emails=classified_df)

classified_df应包含message_id和target列，target列指定目标标签

单邮件路由

# 移动到完成标签(默认TRASH)
connector.move_to_done(emails_id=[message_id])

# 移动到指定标签
connector.move_to(emails_id=[message_id], label_to_move_on="MELUSINE")

最佳实践

1. 标签管理：预先创建好所有可能用到的标签
2. 批量处理：尽量使用批量路由而非单邮件路由
3. 日志记录：合理配置日志级别，便于调试
4. 异常处理：考虑添加重试机制处理API调用失败
5. 性能优化：对于大量邮件，考虑分批处理

常见问题

1. 权限问题：确保OAuth范围包含所有需要的权限
2. 测试模式：开发阶段将应用设置为测试模式并添加测试用户
3. 日期格式：严格遵循YYYY/MM/DD格式
4. 标签不存在：路由前确保目标标签已创建
5. API限制：注意Gmail API的调用频率限制

通过本文的介绍，开发者应该能够充分利用MAIF/melusine项目中的Gmail连接器功能，实现高效的邮件自动化处理流程。