邮件自动化系统

一个基于Node.js、Gmail API和OpenAI的生产级邮件自动化系统,能够自动读取、过滤并智能回复邮件。

  • by khanmadham
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 khanmadham/email-automation-mcp

使用说明

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凭据

  1. 首选 Google 云控制台

  2. 创建一个新项目并启用Gmail API

  3. 创建OAuth 2.0凭据(Web应用程序类型)

  4. 下载JSON文件并提取凭据:

    • GMAIL_CLIENT_ID
    • GMAIL_CLIENT_SECRET
  5. 将凭据添加到 .env:

GMAIL_CLIENT_ID=your_client_id
GMAIL_CLIENT_SECRET=your_client_secret
OPENAI_API_KEY=your_openai_api_key
  1. 运行身份验证流程:
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端点。这 /mcp HTTP端点现已添加。


🏗️ 建筑

处理流水线

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-..."

📝 电子邮件响应个性化

系统使用以下方式个性化响应:

  1. 发件人信息

    • 电子邮件“发件人”字段中的全名
    • 来自电子邮件地址的公司域
    • 电子邮件主题以获取上下文
  2. 规则上下文

    • 匹配规则的上下文描述
    • 电子邮件主题和正文
  3. 人工智能一代

    • 指示模型按姓名向发件人发送地址
    • 保持专业语气
    • 保持回答简洁(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错误

  1. 验证API密钥是否正确:

    echo $OPENAI_API_KEY
    
  2. 检查中的速率限制 OpenAI仪表板

  3. 尝试不同的模型:

    OPENAI_MODEL=gpt-3.5-turbo  # Lower cost
    

电子邮件处理不起作用

  1. 检查日志:

    tail -f logs/combined.log | grep -i error
    
  2. 验证中是否启用了规则 config/rules.json

  3. 使用包含规则中关键字的电子邮件进行测试

  4. 确保在Google云控制台中启用Gmail API

利率限制问题

如果你达到了OpenAI的速率限制:

  1. 增加处理间隔:

    PROCESSING_INTERVAL_MINUTES=15
    
  2. 使用低成本模型:

    OPENAI_MODEL=gpt-3.5-turbo
    
  3. 监控中的使用情况 OpenAI仪表板


💰 成本管理

OpenAI定价

  • gpt-4o-mini:每1000封电子邮件约0.15美元
  • gpt-3.5涡轮增压:每1000封电子邮件约0.05美元
  • 示例:每天100封电子邮件≈每月0.45美元(gpt-4o-mini)

降低成本

  1. 切换到更便宜的型号:

    OPENAI_MODEL=gpt-3.5-turbo
    
  2. 处理频率较低:

    PROCESSING_INTERVAL_MINUTES=30
    
  3. 添加更具体的规则以过滤更少的电子邮件

免费资源

  • 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集成 -自动更新客户记录
  • 通知处理 -过滤并响应警报

🤝 贡献

要扩展系统,请执行以下操作:

  1. 添加筛选规则 -编辑 config/rules.json
  2. 自定义AI响应 -修改 src/ai/openai.js
  3. 扩展电子邮件操作 -更新 src/gmail/emailService.js
  4. 添加新功能 -在中创建模块 src/

⚠️ 重要免责声明

  • 测试 -始终先用有限的电子邮件集进行测试
  • 审查 -在向客户启用之前,审查生成的响应
  • 监控 -定期监控以确保响应质量
  • 合规 -遵守电子邮件法规(CAN-SPAM、GDPR等)
  • 责任 -电子邮件自动发送;确保适当的保障措施

📄 许可证

麻省理工学院


👨‍💻 作者

哈马德·汗 自动化工程师 github: @坎默达姆


📞 支持

对于问题和疑问:

  • 检查 故障排除 部分
  • 查看登录 logs/ 目录
  • 使用启用调试日志记录 LOG_LEVEL=debug