邮件发送

邮件模块提供 SMTP 平台配置、邮件模板、即时发送、营销任务、发送追踪和失败重试能力。当前支持 3 个平台：

平台	平台标识
阿里云 DirectMail	`direct_mail`
腾讯云 SES	`ses`
SendCloud	`send_cloud`

后台菜单位于 邮件营销 下，包含：

邮件发送
营销任务
基本设置
邮件模板

核心流程

即时发送直接返回每个收件人的发送结果。营销任务负责保存发送统计、追踪日志和失败重试数据，适合批量触达和定时发送。

数据结构

邮件模块使用 3 张核心表。

`mail_templates`

字段	说明
`name`	模板名称
`code`	模板唯一标识
`mode`	模板模式：`blade` / `html`
`content`	模板内容
`status`	状态：`1=启用`，`2=禁用`

`mail_send_tasks`

字段	说明
`platform`	发送平台
`from_address`	发件邮箱
`subject`	邮件主题
`template_id`	模板 ID
`send_at`	发送时间，`0` 表示立即发送
`recipients`	收件人邮箱列表
`recipients_num`	收件人数
`success_num` / `failure_num`	成功数 / 失败数
`failure_reason`	任务失败摘要
`status`	状态：`1=未开始`，`2=进行中`，`3=已完成`，`4=失败`
`is_tracking`	追踪开关：`0=关闭`，`1=开启`
`finished_at`	完成时间

`mail_tracking_log`

字段	说明
`task_id`	发送任务 ID
`recipient`	收件人邮箱
`is_delivered`	送达状态
`is_opened`	打开状态
`is_clicked`	点击状态
`is_bounced`	退回状态
`error_message`	发送失败信息
`delivered_at` / `opened_at` / `clicked_at` / `bounced_at` / `failed_at`	各阶段时间

任务与追踪日志通过 task_id 关联，一条营销任务会对应多条收件人日志。

配置

进入后台 邮件营销 -> 基本设置，新增 SMTP 平台配置。

配置项	说明
`平台`	选择 `阿里云 DirectMail`、`腾讯云 SES` 或 `SendCloud`
`SMTP 服务器`	平台提供的 SMTP 地址
`SMTP 端口`	平台提供的 SMTP 端口
`用户名` / `密码`	SMTP 凭据
`加密方式`	`SSL`、`TLS` 或空值
`发件邮箱`	实际用于发送的邮箱地址

端口为 465 且加密方式留空时，系统会按 ssl 处理。保存后，配置会写入动态配置 mails，邮件服务会按平台标识读取对应配置。

邮件模板

进入 邮件营销 -> 邮件模板 创建模板。模板支持两种模式：

模式	说明
`blade`	支持安全变量渲染，适合按收件人生成个性化内容
`html`	直接发送 HTML 内容

Blade 模式可使用：

blade

<p>你好，{{ $recipient['name'] }}</p>
<p>邮箱：{{ $recipient['email'] }}</p>
<p>主题：{{ $task->subject }}</p>

兼容旧占位符：

blade

{{recipient_name}}
{{recipient_email}}
{{task_subject}}

模板渲染器会保留 $recipient 和 $task 的安全取值表达式，并清理 PHP、控制指令和函数调用。模板编辑器提供预览能力，预览数据默认使用测试用户和测试主题。

发送方式

即时发送

进入 邮件营销 -> 邮件发送：

选择已经配置的平台
选择启用中的模板
填写邮件主题
输入一个或多个收件邮箱

收件邮箱支持逗号、分号和换行分隔。提交后，页面会展示每个邮箱的发送结果。

营销任务

进入 邮件营销 -> 营销任务 创建任务。营销任务支持：

立即发送
定时发送
邮件追踪
发送统计
失败邮箱重试

任务执行时会按收件人逐封渲染模板并发送。出现部分失败时，任务状态会显示为已完成，失败数量会记录在 failure_num 中；所有收件人发送失败时，任务状态会记录为失败。

调度任务

营销任务通过 Artisan 命令处理：

shell

php artisan mail:send-tasks --limit=10

线上环境可以在 系统管理 -> 定时任务 中新增调度任务，例如：

配置项	示例
任务名称	邮件营销任务
命令	`mail:send-tasks --limit=10`
执行周期	`everyMinute`

本地调试时可以运行：

shell

php artisan schedule:work

邮件追踪

营销任务开启追踪后，系统会在邮件内容中注入：

打开追踪像素
链接跳转追踪

追踪接口包括：

路径	作用
`GET /api/mail/track/open/{tracking_id}`	记录打开事件
`GET /api/mail/track/click/{tracking_id}`	记录点击事件
`POST /api/mail/track/delivery`	接收送达或退回回调

任务列表页可以查看追踪日志，日志会展示发送、打开、点击、失败等状态。点击“重试失败”后，系统会根据最近一条追踪日志筛选失败邮箱，并创建新的重试任务。

代码调用

完成平台配置后，可以直接通过 MailService 发送邮件：

php

use Modules\Mail\Support\MailService;

$sent = MailService::provider('direct_mail')->send(
    'user@example.com',
    '欢迎加入',
    '<h1>欢迎加入 CatchAdmin</h1>',
    [
        'from' => 'hello@example.com',
        'html' => true,
    ]
);

如果业务需要模板渲染、任务统计、追踪和重试，优先使用营销任务流程。

邮件发送 ​

核心流程 ​

数据结构 ​

mail_templates ​

mail_send_tasks ​

mail_tracking_log ​

配置 ​

邮件模板 ​

发送方式 ​

即时发送 ​

营销任务 ​

调度任务 ​

邮件追踪 ​

代码调用 ​