Laravel Task Scheduler 事务邮件 + Rovela（2026）：Schedule:: 与按窗口幂等键

Laravel Task Scheduler 负责调度 — Rovela 负责投递

Laravel 任务调度用 PHP 定义类 cron 计划——历史上在 app/Console/Kernel.php，现代 Laravel 常在 routes/console.php / bootstrap/app.php 用 Schedule::。服务器上只需一条系统 crontab：* * * * * php artisan schedule:run。Laravel 每分钟判断哪些 Schedule::job / call / command 到期。适合正文依赖触发时 Eloquent 实时状态的摘要。

本文是 调度器 → Rovela 路径——不同于一次性 OTP / magic-link Laravel 发信。

你的任务方法调用 POST https://api.rovela.dev/emails 时，Rovela 负责排队、DKIM 签名与投递（Send Email API、Quick Start、Authentication）。Laravel Task Scheduler 管节奏与「是否到期」；任务方法管聚合、sending_access 密钥，以及按调度窗口稳定的 Idempotency-Key。Rovela 只负责投递。

本指南串联 Laravel Task Scheduler → 任务方法 → Rovela：

1. 声明 Schedule::job(new SendDailyDigestEmail)->dailyAt("09:00")->timezone("UTC")->name("daily-digest-email")->withoutOverlapping()
2. 将 ROVELA_API_KEY（sending_access）、MAIL_FROM、收件人放在仅服务端配置——绝不进浏览器、SPA 或公开 Git
3. 在任务方法内按当前窗口聚合摘要/报告
4. 用窗口级 Idempotency-Key 调用 Rovela
5. 在重试、进程重启、多 Worker 下避免重复发信

Rovela 不会创建 Laravel Task Scheduler 的调度、Worker 或存储。 Laravel Task Scheduler 管 schedule → 触发 → execute；你的方法管查询 → 映射字段 → POST /emails；Rovela 管投递。

与下列文章角度不同：

• Quartz 调度事务邮件 — Java Quartz
• node-cron 事务邮件 — node-cron
• NestJS Schedule Cron 邮件 — NestJS @Cron
• APScheduler Cron 邮件 — APScheduler
• Spring @Scheduled 邮件 — Spring @Scheduled
• Resque-scheduler 邮件 — Resque-scheduler
• RQ Scheduler 邮件 — RQ Scheduler
• delayed_job 周期邮件 — delayed_job
• Solid Queue 周期邮件 — Solid Queue
• Hangfire Recurring 事务邮件 — Hangfire
• Sidekiq-Cron 事务邮件 — Sidekiq-Cron
• Celery Beat 事务邮件 — Celery Beat
• Agenda.js 定时任务邮件 — agenda
• BullMQ 可重复任务邮件 — BullMQ
• Temporal Schedule 邮件 — Temporal
• Trigger.dev Cron 邮件 — Trigger.dev
• Inngest Cron 事务邮件 — Inngest
• Kubernetes CronJob 邮件 — K8s CronJob
• Vercel Cron 摘要邮件 — Vercel cron
• 定时发送邮件 — scheduled_at

也不同于 Laravel OTP 邮件 API（一次性验证）——本文只讲 周期 Task Scheduler。

Laravel Task Scheduler 调度什么，Rovela 发送什么

关注点	归属
计划定义、时区、互斥 / withoutOverlapping	Laravel Schedule::
每分钟一条 OS crontab schedule:run	服务器 crontab / 容器
队列 Worker（若用 Schedule::job）	queue:work / Horizon
ROVELA_API_KEY（sending_access）	进程 / Worker 环境或密钥库
按窗口查库 / 调 API	你的任务方法
渲染 HTML + text	你的任务方法
POST /emails、DKIM、排队、退信	Rovela
Idempotency-Key = laravel-schedule-daily-digest:{yyyy-mm-dd}	你的任务方法

Rovela 返回 200 表示已接受并入队，不是「已进收件箱」。

影响发信任务的 Laravel Task Scheduler 约束

• 应只有一台机器（或 leader）跑 schedule:run。 多机无重叠保护会双发。

• 邮件摘要使用 withoutOverlapping() / onOneServer()。

• 长聚合优先 Schedule::job + 队列，让 schedule:run 保持轻量。

• 时区用 ->timezone(...)。

• 密钥只放 .env / 密钥库。

• sending_access 仅服务端。 放环境变量 / 密钥库，勿进客户端或 Git。

• 优先 HTTPS POST /emails。 Worker 直连 SMTP 通常更差（Email API vs SMTP）。

何时用 Laravel Task Scheduler + POST /emails（而不是 scheduled_at）

在下列情况用 Laravel Task Scheduler → 即时发送：

• HTML 必须在触发时包含新鲜指标
• 已在跑 Laravel Task Scheduler，希望调度与 Worker 同处
• 需要类 cron 摘要，但不想另上 SaaS 调度器
• 运行时查库得到的少量运维/创始人/客户地址

正文已知、只需「稍后投递」时，用 Rovela scheduled_at（定时发送邮件）。Rails 用 Sidekiq-Cron / Solid Queue；NestJS 用 @Cron。

前置条件

1. Rovela 已验证发信域名；未验证 from 会 400。
2. re_… API Key，Worker 优先 sending_access。
3. 已配置调度器的 Laravel 应用，以及每分钟调用 php artisan schedule:run 的单一 OS crontab。
4. 配置：ROVELA_API_KEY、MAIL_FROM、DIGEST_TO。
5. 若使用 ShouldQueue Job，需有队列 Worker。

注册调度

系统 crontab：

* * * * * cd /var/www/app && php artisan schedule:run >> /dev/null 2>&1

Schedule::job(new SendDailyDigestEmail)
    ->dailyAt('09:00')->timezone('UTC')
    ->name('daily-digest-email')
    ->withoutOverlapping()->onOneServer();

调用 Rovela 的任务方法

$idempotencyKey = "laravel-schedule-daily-digest:{$day}";
$response = Http::withToken(env('ROVELA_API_KEY'))
    ->withHeaders(['Idempotency-Key' => $idempotencyKey])
    ->post('https://api.rovela.dev/emails', [
        'from' => env('MAIL_FROM'), 'to' => $to,
        'subject' => $subject, 'html' => $html, 'text' => $text,
        'tags' => ['kind' => 'laravel-schedule-daily-digest', 'day' => $day],
    ]);
if (!$response->successful()) {
    throw new \RuntimeException('Rovela '.$response->status().': '.$response->body());
}

切勿记录 API Key。完整 Job 类见英文版。

窗口级 Idempotency-Key

Rovela 的 Idempotency-Key（最长 256 字符）让 24 小时内相同请求重试返回原响应、不再发第二封。对调度任务很重要：重试会重入方法；Rovela 已 200 但任务未标成功时进程崩溃可能再投递；队列延迟会让墙钟漂移——应按业务窗口键控。

推荐键：laravel-schedule-daily-digest:{yyyy-mm-dd}、laravel-schedule-ops-pulse:{yyyy-mm-dd}T{HH}-{MM}、laravel-schedule-tokyo-ops:{yyyy-mm-dd}、laravel-schedule-weekly-report:{yyyy}-W{ww}、laravel-schedule-tenant-digest:{tenantId}:{yyyy-mm-dd}。

配置密钥并验证调度

1. 在运行调度/Worker 的进程设置 ROVELA_API_KEY（sending_access）、MAIL_FROM、DIGEST_TO。
2. 确认计划项的 cron 与时区。
3. 确认 Worker 在线。
4. 等下一次触发，或在非生产手动触发一次，同时保持窗口 key 稳定。
5. 日志核对 idempotencyKey 与 Rovela emailId。

生产发信优先 sending_access，不要用 full_access。勿记录 API Key。

故障对照

现象	可能原因	处理
Cron 永不触发	调度/Worker 宕机	保持调度进程常开
双发摘要	多调度器/多副本	单一 leader 或分布式锁/持久存储
墙钟时间不对	默认时区错误	显式设置时区
重试后重复摘要	不稳定 key	窗口级 key；24h 内幂等合并
Rovela 401 / 400 / 429	Key / 域名 / 限流	修环境；同 key 重试
密钥进 Git	误提交	只放环境变量 / 密钥库

上线清单

• Rovela 发信域名已验证；MAIL_FROM 匹配
• ROVELA_API_KEY 为 sending_access，仅在 Worker 环境/密钥库
• Laravel Task Scheduler 调度与 Worker 按文档常驻
• 文档化 cron + 时区
• Rovela 发送使用窗口级 Idempotency-Key
• 日志有 emailId 且不打印密钥
• 连续失败 / 调度宕机有告警

FAQ

调度器能不写任务方法直接调 Rovela 吗？没有实质意义——调度器只唤醒你的代码。聚合与 sending_access 必须在你的方法里。Rovela 不托管你的调度器或 Worker。

任务里还要用 scheduled_at 吗？通常不必。调度器已在发送时刻触发且正文是实时的，直接 POST /emails。若现在受理、稍后再投且不想再唤醒进程，才用 scheduled_at（定时发送邮件）。

sending_access 能做什么？足够 POST /emails / batch 入队。读信、改期、取消需要 full_access 或 Dashboard session。Worker 保持 sending_access。

200 等于创始人已收到摘要？否——只表示 Rovela 已接受入队。投递状态看 GET /emails/:id、events 或 webhook。

为何既要调度器重试又要 Idempotency-Key？调度器在代码失败时重试任务；Rovela 的 key 在同一窗口内 HTTP 成功两次（或超时但已接受）时合并重复发送。两层都要。

上线周期任务；让 Rovela 投递

用显式 cron 与时区注册 Laravel Task Scheduler 调度，在任务方法里做实时聚合与 POST /emails，把 Idempotency-Key 限定在调度窗口（及租户），并仅在服务端保存 sending_access。Laravel Task Scheduler 按时唤醒；Rovela 投递事务邮件。