# email-proxy

**Repository Path**: prodigal_son1/email-proxy

## Basic Information

- **Project Name**: email-proxy
- **Description**: 自用。用于clawdbot对话与消息通知推送替代方案
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-29
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Node.js SMTP/IMAP 邮件代理服务

一个基于 Node.js 的轻量级 HTTP 代理服务，将邮件操作抽象为简单的 HTTP API，通过调用第三方邮箱服务商的 SMTP 和 IMAP 协议接口，实现邮件发送和收件箱查询功能。

## 功能特性

- ✅ **JWT 认证**：基于 JWT 的身份验证机制，保护所有接口访问
- ✅ **用户登录**：安全的用户登录接口，生成访问令牌
- ✅ **邮件发送**：支持发送纯文本和 HTML 格式邮件
- ✅ **收件箱查询**：支持获取最新邮件列表，包含完整邮件信息
- ✅ **统一 API**：简洁的 HTTP 接口，无需处理复杂的邮件协议
- ✅ **多邮箱支持**：兼容 QQ、163、Outlook、Gmail 等常见邮箱
- ✅ **安全可靠**：使用 SSL/TLS 加密连接，敏感信息通过环境变量管理
- ✅ **错误处理**：完善的错误处理机制，返回统一的错误格式
- ✅ **跨域支持**：内置 CORS 支持，方便前端调用

## 技术栈

- **后端框架**：Express.js
- **身份验证**：JWT (JSON Web Token)
- **邮件发送**：Nodemailer
- **邮件接收**：Imap + Mailparser
- **配置管理**：Dotenv
- **跨域处理**：CORS

## 安装步骤

### 1. 克隆项目

```bash
git clone <项目仓库地址>
cd email-proxy
```

### 2. 安装依赖

```bash
npm install
```

### 3. 配置邮箱

复制配置模板文件并填写真实配置：

```bash
cp .env.example .env
# 编辑 .env 文件，填写邮箱信息
```

### 4. 启动服务

```bash
node app.js
# 或使用 PM2 管理进程
npm install -g pm2
pm2 start
```

服务默认运行在 `http://localhost:3000`

## 配置说明

在 `.env` 文件中配置以下信息：

| 配置项 | 说明 | 示例值 |
|--------|------|--------|
| PORT | 服务端口 | 3000 |
| EMAIL_USER | 邮箱地址 | your-email@qq.com |
| EMAIL_AUTH_CODE | 邮箱授权码（非登录密码） | your-authorization-code |
| SMTP_HOST | SMTP 服务器地址 | smtp.qq.com |
| SMTP_PORT | SMTP 服务器端口 | 465 |
| IMAP_HOST | IMAP 服务器地址 | imap.qq.com |
| IMAP_PORT | IMAP 服务器端口 | 993 |
| AUTH_USERNAME | 登录用户名 | admin |
| AUTH_PASSWORD | 登录密码 | your-password |
| JWT_SECRET | JWT 密钥 | your-secret-key |

### 常见邮箱配置

#### QQ 邮箱
- SMTP: smtp.qq.com:465
- IMAP: imap.qq.com:993

#### 163 邮箱
- SMTP: smtp.163.com:465
- IMAP: imap.163.com:993

#### Outlook 邮箱
- SMTP: smtp.office365.com:587
- IMAP: outlook.office365.com:993

#### Gmail 邮箱
- SMTP: smtp.gmail.com:465
- IMAP: imap.gmail.com:993

> **注意**：使用前需要在邮箱设置中开启 SMTP/IMAP 服务并获取授权码。

## API 文档

### 1. 健康检查

**请求**：
```
GET /api/test
```

**响应**：
```json
{
  "code": 200,
  "msg": "服务运行正常"
}
```

### 2. 用户登录

**请求**：
```
POST /api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}
```

**参数说明**：
- `username`：必填，登录用户名
- `password`：必填，登录密码

**响应**：
```json
{
  "code": 200,
  "msg": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "24h",
    "user": {
      "username": "admin",
      "role": "user"
    }
  }
}
```

> **注意**：登录成功后，请妥善保存返回的 token，后续所有接口调用都需要在请求头中携带此 token。

### 3. 发送邮件

**请求**：
```
POST /api/send-email
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "to": "recipient1@example.com, recipient2@example.com",
  "subject": "邮件主题",
  "text": "纯文本内容",
  "html": "<p>HTML 内容</p>",
  "attachments": [
    {
      "filename": "example.txt",
      "content": "SGVsbG8sIFdvcmxkIQ==",
      "encoding": "base64"
    }
  ]
}
```

**请求头说明**：
- `Authorization`：必填，格式为 `Bearer <token>`，token 从登录接口获取

**参数说明**：
- `to`：必填，收件人邮箱，多个邮箱用逗号分隔
- `subject`：必填，邮件主题
- `text`：选填，纯文本内容
- `html`：选填，HTML 内容（text 和 html 至少填一个）
- `attachments`：选填，附件数组，每个附件包含：
  - `filename`：必填，附件文件名
  - `content`：必填，附件内容（base64编码）
  - `encoding`：选填，编码方式，默认 base64

**响应**：
```json
{
  "code": 200,
  "msg": "发送成功",
  "data": {
    "messageId": "<message-id@server>",
    "response": "250 OK: queued as ABC123",
    "attachmentsCount": 1
  }
}
```

### 4. 查询收件箱

**请求**：
```
GET /api/get-inbox?limit=10
Authorization: Bearer <your-token>
```

**请求头说明**：
- `Authorization`：必填，格式为 `Bearer <token>`，token 从登录接口获取

**参数说明**：
- `limit`：选填，查询邮件数量，默认 10，最大 50

**响应**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 25,
    "emails": [
      {
        "uid": 123,
        "from": {
          "name": "发件人",
          "address": "sender@example.com"
        },
        "to": [
          {
            "name": "收件人",
            "address": "your-email@qq.com"
          }
        ],
        "subject": "邮件主题",
        "date": "2023-10-27 14:30:00",
        "text": "纯文本正文",
        "html": "<p>HTML 正文</p>"
      }
    ]
  }
}
```

## 部署指南

### 服务器部署

1. **安装依赖**：
   ```bash
   sudo apt update && sudo apt install -y nodejs npm nginx
   ```

2. **上传项目**：
   ```bash
   scp -r email-proxy user@server:/var/www/
   ```

3. **配置 Nginx**：
   ```nginx
   # /etc/nginx/sites-available/email-proxy
   server {
       listen 80;
       server_name your-domain.com;

       location / {
           proxy_pass http://localhost:3000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_cache_bypass $http_upgrade;
       }
   }
   ```

4. **启动服务**：
   ```bash
   cd /var/www/email-proxy
   npm install
   npm install -g pm2
   pm2 start app.js --name email-proxy
   pm2 startup
   pm2 save
   ```

### Docker 部署（可选）

创建 `Dockerfile`：

```dockerfile
FROM node:16-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --production

COPY . .

EXPOSE 3000

CMD ["node", "app.js"]
```

构建并运行：

```bash
docker build -t email-proxy .
docker run -d --name email-proxy -p 3000:3000 --env-file .env email-proxy
```

## 注意事项

1. **授权码获取**：需要在邮箱设置中开启 SMTP/IMAP 服务并获取授权码，授权码不是登录密码
2. **安全性**：`.env` 文件包含敏感信息，请勿提交到版本控制系统
3. **邮件数量**：单次查询邮件数量建议不超过 50，防止超时
4. **网络环境**：确保服务器可以访问邮件服务商的 SMTP/IMAP 服务器
5. **错误处理**：调用 API 时请处理可能的错误响应

## 常见问题

### Q: 登录失败，提示缺少认证配置

**A:** 请确认：
- 已在 `.env` 文件中配置 `AUTH_USERNAME` 和 `AUTH_PASSWORD`
- 已在 `.env` 文件中配置 `JWT_SECRET`
- 配置的值是否正确

### Q: 调用接口时提示认证失败

**A:** 请确认：
- 已通过 `/api/login` 接口登录并获取 token
- 在请求头中正确添加了 `Authorization: Bearer <token>`
- token 是否已过期（默认有效期为 24 小时）
- token 格式是否正确（注意 Bearer 后面有一个空格）

### Q: 发送邮件失败，提示授权码错误

**A:** 请确认：
- 已在邮箱设置中开启 SMTP 服务
- 使用的是授权码而非登录密码
- 授权码是否正确，部分邮箱授权码有有效期

### Q: 查询收件箱返回空数组

**A:** 请确认：
- 已在邮箱设置中开启 IMAP 服务
- 邮箱中有邮件
- 配置的邮箱地址和授权码正确

### Q: 服务启动后无法访问

**A:** 请检查：
- 服务是否正常启动（`pm2 status`）
- 防火墙是否开放对应端口
- Nginx 配置是否正确

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

如有问题，请联系项目维护者。