hsqbh/gmail repository overview

⁠邮箱 → Telegram / PushPlus 转发器

一个用于把邮箱新邮件自动转发到 Telegram、PushPlus，或两者同时接收的 Docker 项目。

支持多种邮箱服务商，包括但不限于：Gmail、QQ 邮箱、163 邮箱、126 邮箱、yeah.net、Outlook、Hotmail、Yahoo、新浪、搜狐、移动、电信、阿里云、iCloud 等。

支持：

• 只转发启动后收到的新邮件，不会补发历史未读
• 接收方式支持：telegram / pushplus / both
• 转发内容包含：原文 + 中文翻译
• 翻译支持通过环境变量切换模型 / 接口
• 适合直接通过 Docker Hub（docker.io） 部署

⁠1. 功能说明

这个项目会定时轮询 Gmail 收件箱（INBOX）：

1. 检查是否有新的未读邮件
2. 读取邮件正文
3. 可选调用 AI 翻译接口，把正文翻译成简体中文
4. 按配置发送到：
   • Telegram
   • PushPlus
   • 或两者同时发送

默认消息内容包含：

• 发件人
• 主题
• 时间
• 原文
• 中文翻译（可关闭）

⁠2. 邮箱应用专用密码 / 授权码怎么申请

⁠2.1 这是什么？

GMAIL_APP_PASSWORD 不是你的邮箱登录密码。

它是邮箱服务商给第三方程序用的应用专用密码或授权码，专门用于 IMAP / SMTP / 第三方客户端登录。

好处：

• 不需要把你的主密码直接写进程序
• 可以单独吊销
• 更安全

⁠2.2 各邮箱服务商授权码申请方式

⁠Gmail

前提条件：必须先开启 Google 账号的两步验证。

1. 开启两步验证：https://myaccount.google.com/security⁠
2. 创建应用专用密码：https://myaccount.google.com/apppasswords⁠
3. 创建后会得到一串 16 位密码，例如：abcd efgh ijkl mnop
4. 写入环境变量时去掉空格：GMAIL_APP_PASSWORD=abcdefghijklmnop

⁠QQ 邮箱 / Foxmail

1. 登录 QQ 邮箱网页版：https://mail.qq.com⁠
2. 点击 设置 → 账户
3. 找到 POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
4. 开启 IMAP/SMTP服务
5. 点击 生成授权码，按提示操作（可能需要发短信验证）
6. 得到一串授权码，例如：abcdefghijklmnop

⁠163 邮箱

1. 登录 163 邮箱网页版：https://mail.163.com⁠
2. 点击 设置 → POP3/SMTP/IMAP
3. 开启 IMAP/SMTP服务
4. 点击 客户端授权密码，按提示操作
5. 得到授权码

⁠126 邮箱

1. 登录 126 邮箱网页版：https://mail.126.com⁠
2. 点击 设置 → POP3/SMTP/IMAP
3. 开启 IMAP/SMTP服务
4. 点击 客户端授权密码，按提示操作
5. 得到授权码

⁠Outlook / Hotmail

1. 登录 Microsoft 账户：https://account.microsoft.com/security⁠
2. 开启 两步验证
3. 创建 应用密码
4. 得到一串密码

⁠Yahoo

1. 登录 Yahoo 账户安全页面
2. 开启 两步验证
3. 生成 应用专用密码
4. 得到授权码

⁠2.3 IMAP 服务器自动识别

本项目支持自动识别常见邮箱的 IMAP 服务器配置，你只需要填写邮箱地址和授权码，无需手动配置 IMAP 服务器和端口。

支持的邮箱服务商：

如果你使用的是上述邮箱，只需要填写邮箱地址和授权码，程序会自动识别对应的 IMAP 配置。

如果你使用的是其他邮箱，或需要自定义配置，可以手动指定：

IMAP_SERVER=imap.example.com
IMAP_PORT=993

⁠3. Telegram Bot 怎么准备

⁠3.1 创建机器人

在 Telegram 中找：

• @BotFather

创建一个 Bot，拿到：

• TELEGRAM_BOT_TOKEN

例如：

TELEGRAM_BOT_TOKEN=123456789:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⁠3.2 获取聊天 ID（chat_id）

先给你的机器人发一条消息，然后访问：

https://api.telegram.org/bot<你的BOT_TOKEN>/getUpdates

在返回 JSON 里找到：

message.chat.id

例如：

TELEGRAM_CHAT_ID=123456789

⁠4. PushPlus 怎么准备

PushPlus 文档：

• 一对一消息说明：https://www.pushplus.plus/doc/function/one.html⁠
• 发送消息接口：https://www.pushplus.plus/doc/guide/api.html⁠
• 接口限制说明：https://www.pushplus.plus/doc/help/limit.html⁠
• 返回码说明：https://www.pushplus.plus/doc/guide/code.html⁠

⁠4.1 基本发送接口

PushPlus 最基本的发送接口是：

• 请求地址：https://www.pushplus.plus/send
• 请求方式：POST

最小请求示例：

{
  "token": "你的token",
  "title": "标题",
  "content": "消息内容"
}

⁠4.2 你在本项目里需要什么？

最少需要：

PUSHPLUS_TOKEN=your_pushplus_token

可选参数：

PUSHPLUS_TEMPLATE=html
PUSHPLUS_CHANNEL=wechat
PUSHPLUS_TOPIC=
PUSHPLUS_TO=

说明：

• PUSHPLUS_TEMPLATE
  • 可选：html / txt / markdown / json
• PUSHPLUS_CHANNEL
  • 默认 wechat
  • 也可以按官方文档改成 webhook / mail / cp / app 等
• PUSHPLUS_TOPIC
  • 群组编码，不填表示发给自己
• PUSHPLUS_TO
  • 好友令牌，不填表示不用好友消息

⁠4.3 使用限制提醒

PushPlus 文档里明确提到：

• 微信渠道有每日次数限制
• 有分钟频率限制
• 相同内容也有限制
• 未实名会返回 905
• 请求过多会返回 900

所以如果你准备用 PushPlus 做高频通知，建议先看官方限制文档。

⁠5. 环境变量说明

Docker Hub 方式运行时，你通常会通过：

• --env-file
• 或 docker run -e

传入这些参数。

⁠Gmail 相关

[email protected]
GMAIL_APP_PASSWORD=xxxxxxxxxxxxxxxx
IMAP_SERVER=imap.gmail.com
IMAP_PORT=993

⁠接收方式

RECEIVER_TYPE=telegram

可选值：

• telegram：只发 Telegram
• pushplus：只发 PushPlus
• both：两边都发

⁠Telegram 相关

TELEGRAM_BOT_TOKEN=xxxxx:xxxxx
TELEGRAM_CHAT_ID=123456789

当 RECEIVER_TYPE=telegram 或 both 时需要。

⁠PushPlus 相关

PUSHPLUS_TOKEN=your_pushplus_token
PUSHPLUS_TEMPLATE=html
PUSHPLUS_CHANNEL=wechat
PUSHPLUS_TOPIC=
PUSHPLUS_TO=

当 RECEIVER_TYPE=pushplus 或 both 时需要。

⁠轮询相关

POLL_SECONDS=10

⁠邮件处理相关

MARK_SEEN=true
FORWARD_HISTORY=false
# [email protected]

说明：

• MARK_SEEN：转发成功后是否标记为已读
• FORWARD_HISTORY：是否转发历史未读邮件
  • false（默认）：只转发启动后收到的新邮件
  • true：启动时会把所有未读邮件都转发一遍
• FORWARD_FROM_FILTER：只转发指定发件人/域名，留空则不过滤

⁠翻译相关

TRANSLATE_ENABLED=true
TRANSLATE_API_BASE=https://qianfan.baidubce.com/v2
TRANSLATE_API_KEY=your_translate_api_key
TRANSLATE_MODEL=ernie-lite-pro-128k

⁠6. Docker Hub（docker.io）使用方式

镜像示例：

hsqbh/gmail:latest

⁠6.1 最推荐：使用 --env-file

先准备一个配置文件，比如：

nano gmail2tg.env

写入：

[email protected]
GMAIL_APP_PASSWORD=your_app_password
IMAP_SERVER=imap.gmail.com
IMAP_PORT=993
RECEIVER_TYPE=both
TELEGRAM_BOT_TOKEN=123456789:bot_token
TELEGRAM_CHAT_ID=123456789
PUSHPLUS_TOKEN=your_pushplus_token
PUSHPLUS_TEMPLATE=html
PUSHPLUS_CHANNEL=wechat
PUSHPLUS_TOPIC=
PUSHPLUS_TO=
POLL_SECONDS=10
MARK_SEEN=true
TRANSLATE_ENABLED=true
TRANSLATE_API_BASE=https://qianfan.baidubce.com/v2
TRANSLATE_API_KEY=your_translate_key
TRANSLATE_MODEL=ernie-lite-pro-128k

启动：

docker run -d \
  --name gmail2tg \
  --restart unless-stopped \
  --env-file ./gmail2tg.env \
  hsqbh/gmail:latest

⁠6.2 直接使用 docker run -e

docker run -d \
  --name gmail2tg \
  --restart unless-stopped \
  -e GMAIL_EMAIL="[email protected]" \
  -e GMAIL_APP_PASSWORD="your_app_password" \
  -e IMAP_SERVER="imap.gmail.com" \
  -e IMAP_PORT="993" \
  -e RECEIVER_TYPE="both" \
  -e TELEGRAM_BOT_TOKEN="123456789:bot_token" \
  -e TELEGRAM_CHAT_ID="123456789" \
  -e PUSHPLUS_TOKEN="your_pushplus_token" \
  -e PUSHPLUS_TEMPLATE="html" \
  -e PUSHPLUS_CHANNEL="wechat" \
  -e PUSHPLUS_TOPIC="" \
  -e PUSHPLUS_TO="" \
  -e POLL_SECONDS="10" \
  -e MARK_SEEN="true" \
  -e TRANSLATE_ENABLED="true" \
  -e TRANSLATE_API_BASE="https://qianfan.baidubce.com/v2" \
  -e TRANSLATE_API_KEY="your_translate_key" \
  -e TRANSLATE_MODEL="ernie-lite-pro-128k" \
  hsqbh/gmail:latest

注意：Docker 传环境变量用的是 -e，不是 -E。

⁠6.3 查看日志

docker logs -f gmail2tg

⁠6.4 停止容器

docker stop gmail2tg

⁠6.5 启动已存在的容器

docker start gmail2tg

⁠6.6 重启容器

docker restart gmail2tg

⁠6.7 删除容器

docker rm -f gmail2tg

⁠6.8 更新镜像

docker pull hsqbh/gmail:latest
docker rm -f gmail2tg

然后重新执行 docker run ...。

⁠7. 当前程序行为说明

⁠只转发新邮件

程序启动时会先记录当前所有未读邮件 ID，把它们当作历史存量：

• 不补发历史未读
• 只处理启动后新增的未读邮件

⁠过滤逻辑

如果设置了：

[email protected]

只有发件人中包含 @example.com 的邮件才会转发。

⁠翻译失败时的行为

如果翻译接口报错：

• 程序不会直接崩掉
• 邮件仍会继续尝试发送
• 翻译部分会显示"翻译失败"

⁠8. License

本项目附带：

• LICENSE（MIT License）

⁠9. 安全提醒

• 不要把包含真实密钥的 env 文件公开分享
• GMAIL_APP_PASSWORD、TELEGRAM_BOT_TOKEN、PUSHPLUS_TOKEN、TRANSLATE_API_KEY 都属于敏感信息
• 如果泄露，请尽快重置