# gmail_imap

**Repository Path**: tkgzone/gmail_imap

## Basic Information

- **Project Name**: gmail_imap
- **Description**: Bun + TypeScript + IMAP；gmail配置：先开启两步验证，并生成应用专用密码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-24
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gmail 验证码助手

添加 Gmail 账号（邮箱 + 应用专用密码），输入邮箱后每 5 秒自动拉取新邮件，并自动提取验证码、一键复制。

- 后端：Bun + TypeScript，IMAP 用 [imapflow](https://github.com/postalsys/imapflow)，邮件解析用 mailparser
- 存储：`data/accounts.sqlite`，只保存账号信息（邮箱、应用专用密码、连通状态），**不保存任何邮件**
- 前端：`public/` 下的原生 TS 页面，由 Bun 的 HTML import 自动打包

![页面展示](./review.png)

## 启动

```bash
bun install
bun run dev      # 开发模式（改代码自动重载），默认 http://127.0.0.1:3000
bun run start    # 生产模式
```

可选环境变量（也可以写在 `.env` 里，Bun 会自动加载）：

| 变量           | 默认值                   | 说明                                                                                                                 |
| -------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `PORT`       | `3000`                 | 服务端口                                                                                                             |
| `HOST`       | `127.0.0.1`            | 监听地址；服务没有登录鉴权，不建议改成`0.0.0.0` 暴露到局域网                                                       |
| `DB_PATH`    | `data/accounts.sqlite` | SQLite 文件路径                                                                                                      |
| `IMAP_PROXY` | 无                       | 连接 Gmail 的代理，如`socks5://127.0.0.1:7890` 或 `http://127.0.0.1:7890`（`HTTP_PROXY` 等变量对 IMAP 不生效） |

## 功能说明

- **添加邮箱**：会实际登录一次 `imap.gmail.com:993` 校验，失败时把原因返回给前端；同一个邮箱不能重复添加（`a.b.c@gmail.com` 与 `abc@gmail.com` 视为同一个）。
- **搜索**：输入邮箱点击搜索后，显示「点击时刻往前 3 分钟」之后收到的邮件（收件箱 + 垃圾邮件），之后每 5 秒自动刷新，也可以点「手动刷新」。刷新出错会在页面上显示红色提示。
- **别名**：搜索 `abc+shop@gmail.com`、`a.bc@gmail.com` 这类别名时，会找到对应账号，并且只显示发给这个别名的邮件。
- **账户状态**：添加、检测、每次刷新都会更新状态（正常 / 异常 + 错误原因），可单个检测、全部检测、删除。
- **验证码**：从主题和正文中自动识别，点击验证码或「一键复制」即可复制。

## 手动调试方法

### 1. 先确认网络能连上 Gmail IMAP

```bash
openssl s_client -connect imap.gmail.com:993 -quiet
# 能看到 "* OK Gimap ready" 说明网络通，Ctrl+C 退出
```

连不上时设置 `IMAP_PROXY` 后重启服务。

### 2. 在页面上按顺序验证

1. 添加账号：输入邮箱和应用专用密码，成功后账户列表出现绿色「正常」。密码填错时应显示「认证失败」。
2. 实时收信：点该账号的「搜索」，再用**另一个邮箱**给它发一封正文为 `您的验证码为：123456` 的邮件，5 秒左右应出现，并显示验证码 `123456` 和「一键复制」按钮。
3. 往前 3 分钟：先发一封邮件，等 1～2 分钟后再点搜索，这封邮件应该出现；超过 3 分钟的邮件不会出现。
4. 别名：给 `你的邮箱名+test@gmail.com` 发邮件，然后搜索这个别名，应只显示发给该别名的邮件。
5. 报错：监听过程中断开网络（或关掉代理），页面应出现红色「刷新失败」提示，账户变为「异常」；恢复网络后下一次刷新自动恢复。

### 3. 用 curl 直接调接口（绕过前端）

```bash
# 账号列表
curl localhost:3000/api/accounts

# 添加账号
curl -X POST localhost:3000/api/accounts -H 'content-type: application/json' \
  -d '{"email":"name@gmail.com","password":"abcd efgh ijkl mnop"}'

# 检测账号连通性（1 为账号 id）
curl -X POST localhost:3000/api/accounts/1/check

# 拉取最近 3 分钟的邮件（前端每 5 秒调用的就是这个接口）
curl -X POST localhost:3000/api/mails -H 'content-type: application/json' \
  -d "{\"email\":\"name@gmail.com\",\"since\":$(( $(date +%s%3N) - 180000 )),\"known\":[]}"

# 删除账号
curl -X DELETE localhost:3000/api/accounts/1
```

出错时接口返回 `{"error": "原因"}`，同时会带上对应的 HTTP 状态码（400 参数错误 / 404 账号不存在 / 409 重复添加 / 422 添加时连通性校验失败 / 502 IMAP 拉取失败）。

### 4. 看日志和数据

- 服务终端：拉取失败时会打印 `[search] 邮箱: 错误原因`。
- 浏览器 F12 → Network：可以看到每 5 秒一次的 `/api/mails` 请求和返回的 JSON（`code` 字段就是识别出的验证码）。
- 查看数据库里的账号状态：

  ```bash
  bun -e 'import { Database } from "bun:sqlite"; console.table(new Database("data/accounts.sqlite").query("SELECT id, email, status, last_error FROM accounts").all())'
  ```

## 常见错误

| 提示                               | 原因                                                           |
| ---------------------------------- | -------------------------------------------------------------- |
| 认证失败：邮箱或应用专用密码不正确 | 密码错误、已被撤销，或填的是 Google 登录密码而不是应用专用密码 |
| 需要使用应用专用密码               | 账号没开两步验证，或填了普通密码                               |
| 连接 imap.gmail.com 超时           | 网络不通，需要设置`IMAP_PROXY`                               |
| 该账号未开启 IMAP 访问             | 在 Gmail 设置 → 转发和 POP/IMAP 中启用 IMAP                   |