SMTP 邮件推送渠道配置指南

本教程将指导你如何在 MagicPush（魔法推送）中配置 SMTP 邮件推送渠道，实现通过邮件服务发送通知。

概述

什么是 SMTP 邮件推送？

SMTP（Simple Mail Transfer Protocol）是标准的邮件发送协议。MagicPush 通过 nodemailer 库连接任意 SMTP 服务器，将消息以邮件形式发送到指定收件人。

特点	说明
推送目标	任意有效邮箱地址
鉴权方式	用户名 + 密码/授权码
配置复杂度	中，需要 SMTP 服务器信息
消息格式	text（纯文本）、html（HTML 邮件）
频率限制	取决于 SMTP 服务商

前置条件

拥有可用的邮箱账号（QQ 邮箱、163 邮箱、Gmail、企业邮箱等）
已获取邮箱的 SMTP 服务权限（通常需要开启 SMTP 并获取授权码）
已部署并登录 MagicPush 管理后台

第一步：获取邮箱 SMTP 配置信息

1.1 常见邮箱 SMTP 配置

QQ 邮箱

登录 QQ 邮箱
点击顶部 「设置」 → 「账户」
找到 「POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务」 部分
开启 「IMAP/SMTP 服务」
按提示用手机发送短信验证
验证成功后，会显示 授权码（不是 QQ 密码）

📌 QQ 邮箱 SMTP 配置：
SMTP 服务器：smtp.qq.com
端口：465（SSL）或 587（TLS）
密码：使用授权码，不是 QQ 密码

163 邮箱

登录 163 邮箱
点击顶部 「设置」 → 「POP3/SMTP/IMAP」
开启 「SMTP 服务」
设置客户端授权密码（不是 163 邮箱密码）

📌 163 邮箱 SMTP 配置：
SMTP 服务器：smtp.163.com
端口：465（SSL）或 25（非加密）
密码：使用客户端授权密码

Gmail

登录 Gmail
点击右上角头像 → 「管理您的 Google 账号」
左侧导航选择 「安全性」
找到 「两步验证」 并开启
开启后，返回 「安全性」 → 「应用密码」
生成新的应用专用密码

📌 Gmail SMTP 配置：
SMTP 服务器：smtp.gmail.com
端口：465（SSL）或 587（TLS）
密码：使用应用专用密码，不是 Gmail 密码

企业邮箱（以阿里云邮箱为例）

📌 阿里云邮箱 SMTP 配置：
SMTP 服务器：smtp.mxhichina.com
端口：465（SSL）
密码：使用邮箱登录密码

1.2 SMTP 配置参数汇总

邮箱服务	SMTP 服务器	端口	加密方式	密码类型
QQ 邮箱	`smtp.qq.com`	465	SSL	授权码
163 邮箱	`smtp.163.com`	465	SSL	客户端授权码
Gmail	`smtp.gmail.com`	465 / 587	SSL/TLS	应用专用密码
Outlook	`smtp.office365.com`	587	STARTTLS	邮箱密码
阿里云邮箱	`smtp.mxhichina.com`	465	SSL	邮箱密码
腾讯企业邮箱	`smtp.exmail.qq.com`	465	SSL	邮箱密码

第二步：在 MagicPush 中添加渠道

2.1 进入渠道管理

登录 MagicPush 管理后台（默认地址 http://<服务器IP>:3000）
点击左侧导航 「渠道管理」
点击右上角 「+ 绑定渠道」 按钮

2.2 选择渠道类型

在弹出的对话框中，从渠道类型下拉列表中选择 「SMTP邮件」。

2.3 填写配置信息

根据第一步获取的信息，填写以下配置字段：

字段	说明	示例
SMTP 服务器	SMTP 服务器地址	`smtp.qq.com`
端口	SMTP 服务端口	`465`（SSL）或 `587`（TLS）
启用 SSL/TLS	是否使用加密连接	端口 465 开启，端口 587 关闭
用户名	邮箱账号	`123456789@qq.com`
密码/授权码	邮箱密码或授权码	`abcd efgh ijkl mnop`
发件人地址（可选）	自定义发件人地址，留空则使用用户名	`noreply@example.com`
收件人地址	接收通知的邮箱，多个用逗号分隔	`user1@example.com,user2@example.com`

💡 重要提示：
密码字段填写的是授权码，不是邮箱登录密码（QQ 邮箱、163 邮箱等）
Gmail 需要使用应用专用密码，先开启两步验证
端口 465 通常需要开启 SSL，端口 587 使用 STARTTLS（MagicPush 会自动处理）

填写完成后，给渠道起一个易于辨识的名称（如「运维邮件通知」），点击 「保存」。

2.4 测试连通性

渠道创建成功后，在渠道卡片右侧的下拉菜单中，点击 「测试」 按钮。

✅ 如果收件邮箱收到「这是一条来自魔法推送的测试消息」邮件，说明配置成功
❌ 如果测试失败，请参考下方常见问题排查

第三步：使用推送

3.1 通过 API 推送

创建渠道后，可以通过 MagicPush 的标准 API 进行推送：

bash

curl -X POST http://<服务器IP>:3000/api/push/<渠道ID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的API Token>" \
  -d '{
    "title": "服务器告警通知",
    "content": "生产环境服务器 CPU 使用率超过 90%，请立即处理。\n\n时间：2024-06-01 14:00:00\n服务器：192.168.1.100",
    "type": "text"
  }'

支持的消息类型（type 参数）：

type 值	说明
`text`	纯文本邮件（默认）
`html`	HTML 格式邮件（支持富文本样式）

3.2 HTML 邮件示例

当 type 为 html 时，可以在 content 中使用 HTML 标签：

html

<h2>🚨 服务器告警通知</h2>
<p><strong>告警级别：</strong><span style="color:red;">高</span></p>
<p><strong>服务器：</strong>192.168.1.100</p>
<p><strong>时间：</strong>2024-06-01 14:00:00</p>
<p><strong>详情：</strong>CPU 使用率超过 90%</p>
<hr>
<p><a href="https://monitor.example.com/alert/12345">查看详情</a></p>

技术细节

邮件大小限制

大多数邮箱服务限制邮件大小为 10-25 MB（含附件）
MagicPush 当前不支持附件，仅发送文本内容
纯文本邮件通常远小于限制

连接安全性

端口	加密方式	说明
465	SSL/TLS	推荐，全程加密
587	STARTTLS	推荐，先明文后升级加密
25	无加密	不推荐，可能被拦截

💡 MagicPush 使用 nodemailer 库，会根据 secure 配置自动选择加密方式。

常见 SMTP 错误码

错误码	说明	解决方法
535	认证失败	检查用户名/密码（授权码）是否正确
554	拒绝服务	IP 可能在黑名单中，或内容被识别为垃圾邮件
421	连接过多	SMTP 服务限流，降低发送频率

常见问题

Q: 发送邮件返回「认证失败」错误？

原因：用户名或密码（授权码）填写错误。

解决：

确认密码填写的是授权码，不是邮箱登录密码（QQ、163 等）
Gmail 需要使用应用专用密码，不是账号密码
重新获取授权码并填写

Q: QQ 邮箱无法发送，提示需要开启 IMAP/SMTP？

原因：QQ 邮箱默认关闭 SMTP 服务。

解决：

登录 QQ 邮箱网页版
设置 → 账户 → 开启「IMAP/SMTP 服务」
按提示用手机发送短信验证
获取授权码后重新配置

Q: Gmail 无法发送，提示「不太安全的应用」？

原因：Google 已不再允许「不太安全的应用」访问。

解决：

开启 Gmail 的两步验证
在 Google 账号安全性设置中生成应用专用密码
在 MagicPush 中使用应用专用密码代替 Gmail 密码

Q: 测试邮件能收到，但实际推送收不到？

原因：可能被标记为垃圾邮件，或触发了频率限制。

解决：

检查垃圾邮件文件夹
降低发送频率（特别是 QQ 邮箱，有较严格的限流策略）
确保邮件内容不包含敏感词

Q: 如何同时发送给多个收件人？

解决：在 「收件人地址」 字段中，用英文逗号分隔多个邮箱地址：

user1@example.com,user2@example.com,user3@example.com

Q: 端口和 SSL 应该如何搭配？

端口	SSL 开关	说明
465	开启（true）	标准 SSL 端口，推荐
587	关闭（false）	STARTTLS 端口，MagicPush 会自动协商加密
25	关闭（false）	非加密端口，不推荐

SMTP 邮件推送渠道配置指南 ​

概述 ​

什么是 SMTP 邮件推送？ ​

前置条件 ​

第一步：获取邮箱 SMTP 配置信息 ​

1.1 常见邮箱 SMTP 配置 ​

QQ 邮箱 ​

163 邮箱 ​

Gmail ​

企业邮箱（以阿里云邮箱为例） ​

1.2 SMTP 配置参数汇总 ​

第二步：在 MagicPush 中添加渠道 ​

2.1 进入渠道管理 ​

2.2 选择渠道类型 ​

2.3 填写配置信息 ​

2.4 测试连通性 ​

第三步：使用推送 ​

3.1 通过 API 推送 ​

3.2 HTML 邮件示例 ​

技术细节 ​

邮件大小限制 ​

连接安全性 ​

常见 SMTP 错误码 ​

常见问题 ​

Q: 发送邮件返回「认证失败」错误？ ​

Q: QQ 邮箱无法发送，提示需要开启 IMAP/SMTP？ ​

Q: Gmail 无法发送，提示「不太安全的应用」？ ​

Q: 测试邮件能收到，但实际推送收不到？ ​

Q: 如何同时发送给多个收件人？ ​

Q: 端口和 SSL 应该如何搭配？ ​

参考资源 ​