使用说明
AI电子邮件自动化系统
使用Node.js、Gmail API和OpenAI构建的生产就绪电子邮件自动化系统,可自动读取传入电子邮件,根据规则进行过滤,并生成智能回复。
✨ 主要特点
- Gmail OAuth2集成 -使用Google Workspace进行安全身份验证
- AI驱动的响应 -使用OpenAI生成个性化电子邮件
- 基于规则的过滤 -电子邮件匹配逻辑的灵活配置
- 自动调度 -使用cron在可配置的时间间隔内处理电子邮件
- 详细日志记录 -使用Winston日志记录监控系统活动
- 生产就绪 -模块化架构,具有错误处理和优雅关机功能
🚀 快速开始
先决条件
- Node.js 16+
- npm或纱线
- OpenAI API密钥
- 启用Gmail API的谷歌云项目
安装
# Clone the repository
git clone <repository-url>
cd email-automation
# Install dependencies
npm install
# Copy environment template
cp .env.example .env
设置Gmail凭据
-
首选 Google 云控制台
-
创建一个新项目并启用Gmail API
-
创建OAuth 2.0凭据(Web应用程序类型)
-
下载JSON文件并提取凭据:
GMAIL_CLIENT_IDGMAIL_CLIENT_SECRET
-
将凭据添加到
.env:
GMAIL_CLIENT_ID=your_client_id
GMAIL_CLIENT_SECRET=your_client_secret
OPENAI_API_KEY=your_openai_api_key
- 运行身份验证流程:
npm run setup
这产生了 GOOGLE_TOKEN_JSON 您将添加到 .env.
启动系统
npm start
系统将按照配置的时间间隔初始化并开始处理电子邮件。
🔌 连接克劳德桌面(MCP)
服务器暴露了一个 流式HTTP MCP传输 在 http://localhost:3000/mcp.
步骤1--启动服务器
npm start
步骤2--添加到Claude桌面
打开 克劳德桌面版→ 设置→ 开发者→ 编辑配置 并添加:
{
"mcpServers": {
"email-automation": {
"url": "http://localhost:3000/mcp"
}
}
}
保存文件并 重新启动克劳德桌面MCP服务器将出现在Claude的工具面板中。
注: 如果你以前见过 “连接到MCP服务器时出错”,这是因为服务器只支持stdio传输,没有HTTP MCP端点。这
/mcpHTTP端点现已添加。
🏗️ 建筑
处理流水线
1. Scheduler triggers every N minutes
↓
2. Fetch unread emails from Gmail
↓
3. For each email, apply filtering rules
↓
4. If email matches rules:
- Extract sender information
- Send to OpenAI for response generation
- Generate personalized reply
↓
5. Send reply to original sender
↓
6. Mark as read and label "AutoReplied"
项目结构
email-automation/
├── config/
│ ├── rules.json # Email filtering rules
│ └── settings.json # Application settings
├── src/
│ ├── gmail/
│ │ ├── auth.js # OAuth 2.0 authentication
│ │ ├── emailService.js # Gmail API operations
│ │ └── setup.js # Authentication flow
│ ├── filters/
│ │ └── engine.js # Rule evaluation engine
│ ├── ai/
│ │ └── openai.js # OpenAI integration
│ ├── processor/
│ │ └── emailProcessor.js # Email processing pipeline
│ ├── scheduler/
│ │ └── cronScheduler.js # Cron scheduling
│ ├── utils/
│ │ └── logger.js # Winston logging setup
│ └── index.js # Application entry point
├── logs/ # Application logs (auto-created)
├── package.json
├── .env # Environment variables
├── .env.example # Environment template
└── README.md
🔧 配置
环境变量
创建一个 .env 文件包含:
# Gmail OAuth Credentials
GMAIL_CLIENT_ID=your_client_id
GMAIL_CLIENT_SECRET=your_client_secret
GMAIL_REDIRECT_URI=http://localhost:3000/oauth/callback
# Google Auth Token (generated by npm run setup)
GOOGLE_TOKEN_JSON='{"type":"authorized_user",...}'
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4o-mini
# Processing Configuration
PROCESSING_INTERVAL_MINUTES=5
LOG_LEVEL=info
电子邮件筛选规则
编辑 config/rules.json 要定义哪些电子邮件应自动回复:
{
"rules": [
{
"id": "pricing_inquiry",
"name": "Pricing Request Auto-Reply",
"enabled": true,
"conditions": {
"keywords": ["pricing", "cost", "plans"],
"mustMatch": "any"
},
"context": "Customer is asking about pricing and subscription options"
}
]
}
规则属性:
id-规则的唯一标识符name-人类可读的规则名称enabled-启用/禁用而不删除conditions.keywords-要匹配的关键字数组conditions.mustMatch-比赛策略:"any"或"all"context-将上下文发送到OpenAI以生成响应
📊 技术栈
| 组件 | 技术 |
|---|---|
| 运行时 | Node.js |
| 电子邮件API | Gmail API |
| 人工智能时代 | OpenAI |
| 调度 | 节点Cron |
| 日志 | 温斯顿 |
| 语言 | JavaScript(ES模块) |
🔐 安全
凭据管理
- OAuth令牌 -存储在环境变量中,从不提交
- API密钥 -坚持住
.env文件(添加到.gitignore) - 电子邮件数据 -在发送给OpenAI之前,山宁泰
- .env文件 -确保添加到
.gitignore
最佳实践
# Never commit credentials
echo ".env" >> .gitignore
echo "credentials.json" >> .gitignore
# Use environment variables for sensitive data
export OPENAI_API_KEY="sk-..."
📝 电子邮件响应个性化
系统使用以下方式个性化响应:
-
发件人信息
- 电子邮件“发件人”字段中的全名
- 来自电子邮件地址的公司域
- 电子邮件主题以获取上下文
-
规则上下文
- 匹配规则的上下文描述
- 电子邮件主题和正文
-
人工智能一代
- 指示模型按姓名向发件人发送地址
- 保持专业语气
- 保持回答简洁(2-3句话)
示例流程
User email: "Hi, I'm interested in your pricing plans"
↓
Matches rule: "Pricing Request Auto-Reply"
↓
OpenAI generates:
"Hi John, thanks for your interest! Our pricing plans start at $X/month
and include feature Y and Z. Would you like to schedule a demo?"
↓
Reply sent to: user@company.com
📊 监控和记录
日志文件
日志保存到 logs/ 目录:
combined.log-所有日志消息error.log-仅错误消息
实时监控
# Watch logs in real-time
tail -f logs/combined.log
# Filter for errors only
tail -f logs/error.log
日志级别
集 LOG_LEVEL 在 .env:
LOG_LEVEL=debug # Verbose output (development)
LOG_LEVEL=info # Standard output (default)
LOG_LEVEL=warn # Warnings and errors only
LOG_LEVEL=error # Errors only
🚨 故障排除
未找到Gmail凭据
npm run setup
系统将引导您完成OAuth身份验证并生成所需的令牌。
“以降级模式启动”消息
这意味着Gmail凭据丢失。应用程序将启动,但电子邮件处理已禁用。跑 npm run setup 配置凭据。
OpenAI API错误
-
验证API密钥是否正确:
echo $OPENAI_API_KEY -
检查中的速率限制 OpenAI仪表板
-
尝试不同的模型:
OPENAI_MODEL=gpt-3.5-turbo # Lower cost
电子邮件处理不起作用
-
检查日志:
tail -f logs/combined.log | grep -i error -
验证中是否启用了规则
config/rules.json -
使用包含规则中关键字的电子邮件进行测试
-
确保在Google云控制台中启用Gmail API
利率限制问题
如果你达到了OpenAI的速率限制:
-
增加处理间隔:
PROCESSING_INTERVAL_MINUTES=15 -
使用低成本模型:
OPENAI_MODEL=gpt-3.5-turbo -
监控中的使用情况 OpenAI仪表板
💰 成本管理
OpenAI定价
- gpt-4o-mini:每1000封电子邮件约0.15美元
- gpt-3.5涡轮增压:每1000封电子邮件约0.05美元
- 示例:每天100封电子邮件≈每月0.45美元(gpt-4o-mini)
降低成本
-
切换到更便宜的型号:
OPENAI_MODEL=gpt-3.5-turbo -
处理频率较低:
PROCESSING_INTERVAL_MINUTES=30 -
添加更具体的规则以过滤更少的电子邮件
免费资源
- Gmail API:免费(在配额限制内)
- Node.js:免费开源
🔧 高级配置
热重载规则
修改规则而不重新启动:
import { reloadRules } from './src/filters/engine.js';
reloadRules(); // Reloads rules.json
自定义响应逻辑
编辑 src/processor/emailProcessor.js 自定义:
- 响应生成逻辑
- 电子邮件过滤标准
- 后处理步骤
批处理
一次处理多封电子邮件:
import { processUnreadEmails } from './src/processor/emailProcessor.js';
const results = await processUnreadEmails(10);
console.log(`Processed: ${results.length} emails`);
数据库集成
对于电子邮件历史记录跟踪,添加SQLite:
npm install better-sqlite3
📚 用例
- 客户支持 -自动回复常见问题
- 超前响应 -自动确认查询请求
- 业务自动化 -处理日常电子邮件工作流程
- CRM集成 -自动更新客户记录
- 通知处理 -过滤并响应警报
🤝 贡献
要扩展系统,请执行以下操作:
- 添加筛选规则 -编辑
config/rules.json - 自定义AI响应 -修改
src/ai/openai.js - 扩展电子邮件操作 -更新
src/gmail/emailService.js - 添加新功能 -在中创建模块
src/
⚠️ 重要免责声明
- 测试 -始终先用有限的电子邮件集进行测试
- 审查 -在向客户启用之前,审查生成的响应
- 监控 -定期监控以确保响应质量
- 合规 -遵守电子邮件法规(CAN-SPAM、GDPR等)
- 责任 -电子邮件自动发送;确保适当的保障措施
📄 许可证
麻省理工学院
👨💻 作者
哈马德·汗 自动化工程师 github: @坎默达姆
📞 支持
对于问题和疑问:
- 检查 故障排除 部分
- 查看登录
logs/目录 - 使用启用调试日志记录
LOG_LEVEL=debug