RQ Scheduler Transactional Email with Rovela (2026): cron + Idempotency-Key per Window

RQ Scheduler owns the schedule — Rovela delivers the mail

RQ Scheduler adds cron and delayed scheduling on top of RQ (Redis Queue). You call scheduler.cron(...) (or manage jobs via the scheduler CLI), run an rqscheduler process plus rq worker processes, and Redis holds both queues and schedule state. That fits digests whose body depends on live DB state at fire time.

Distinct from APScheduler Cron Email (in-process) and Celery Beat Transactional Email — this post is RQ + rq-scheduler.

Rovela queues, DKIM-signs, and delivers when your job method calls POST https://api.rovela.dev/emails (Send Email API, Quick Start, Authentication). RQ Scheduler owns the cadence and “is due?” logic. Your job method owns aggregation, secrets for sending_access, and a stable Idempotency-Key per schedule window. Rovela only delivers.

This guide wires RQ Scheduler → job method → Rovela that:

1. Declares scheduler.cron("0 9 * * *", func=send_daily_digest, id="daily-digest-email", queue_name="mailers") and runs rqscheduler + workers
2. Keeps ROVELA_API_KEY (sending_access), MAIL_FROM, and recipients in server-only config — never in browsers, SPA bundles, or a public Git tree
3. Aggregates a digest / report for the current schedule window inside the job method
4. Sends via Rovela with a window-scoped Idempotency-Key
5. Survives retries, restarts, and multi-worker fleets without duplicate mail

Rovela does not create RQ Scheduler schedules, workers, or storage. RQ Scheduler owns schedule → enqueue/fire → execute. Your job method owns query → map fields → POST /emails. Rovela owns delivery.

Distinct from:

• Quartz Scheduler Transactional Email — Java Quartz
• node-cron Transactional Email — node-cron
• NestJS Schedule Cron Email — NestJS @Cron
• Laravel Task Scheduler Email — Laravel Schedule::
• APScheduler Cron Email — APScheduler
• Spring @Scheduled Email — Spring @Scheduled
• Resque-scheduler Email — Resque-scheduler
• delayed_job Recurring Email — delayed_job
• Solid Queue Recurring Email — Solid Queue
• Hangfire Recurring Jobs Email — Hangfire
• Sidekiq-Cron Transactional Email — Sidekiq-Cron
• Celery Beat Transactional Email — Celery Beat
• Agenda.js Scheduled Jobs Email — agenda
• BullMQ Repeatable Email — BullMQ
• Temporal Schedule Email — Temporal
• Trigger.dev Cron Email — Trigger.dev
• Inngest Cron Transactional Email — Inngest
• Kubernetes CronJob Email — K8s CronJob
• Vercel Cron Digest Email — Vercel cron
• Scheduled Email Sending — scheduled_at

Also distinct from platform cron that curls an HTTP route — RQ keeps work inside your Redis-backed workers.

What RQ Scheduler schedules vs what Rovela sends

Concern	Owner
cron expression, job id, queue	RQ Scheduler (rqscheduler)
Redis broker + RQ workers	RQ
Job function execution	Your Python function / job
Server secrets for ROVELA_API_KEY (sending_access)	Process / worker env / secret store
Query DB / APIs for the window	Your job method
Render HTML + text	Your job method
POST /emails, DKIM, queue, bounces	Rovela
Idempotency-Key = rq-scheduler-daily-digest:{yyyy-mm-dd}	Your job method

A 200 from Rovela means accepted and queued, not “already in the inbox” (Quick Start).

RQ Scheduler constraints that shape the email job

• Run one rqscheduler process (HA carefully) — multiple schedulers can double-enqueue.

• Workers must listen on the same queue the cron targets.

• Job functions must be importable by workers (module path stability).

• Keep ROVELA_API_KEY in worker env, not in Redis job kwargs if avoidable.

• Prefer Celery Beat when you already run Celery; prefer APScheduler when you want no Redis.

• Keep sending_access server-only. Store ROVELA_API_KEY in environment / vault — never in client apps or public Git (Authentication).

• Prefer HTTPS POST /emails. Outbound SMTP from a worker is a poor fit (Email API vs SMTP).

When to use RQ Scheduler + POST /emails (not scheduled_at)

Use RQ Scheduler → live send when:

• The HTML must include fresh metrics at fire time
• You already run RQ Scheduler and want schedules next to the same workers
• You need cron-like digests without adopting a separate SaaS scheduler
• One (or a few) transactional messages go to ops / founder / customer addresses looked up at run time

Use Rovela scheduled_at when the body is already correct and you only need “deliver later” without a running scheduler (Scheduled Email Sending). Prefer RQ Scheduler when Redis+RQ is already your queue; prefer Celery Beat for Celery stacks.

Prerequisites

1. A verified sending domain in Rovela. Unverified from domains are refused with 400 (Quick Start).
2. An API key shaped like re_…. Prefer sending_access for the worker (Authentication).
3. Python app with rq, rq-scheduler, Redis, one rqscheduler, and RQ workers.
4. Config: ROVELA_API_KEY, MAIL_FROM, DIGEST_TO.
5. Importable job functions and Redis URL config.

Register the schedule

pip install rq rq-scheduler

# schedule_boot.py — run once at deploy / in a management command
from redis import Redis
from rq_scheduler import Scheduler
from jobs.digest import send_daily_digest, send_ops_pulse

scheduler = Scheduler(queue_name="mailers", connection=Redis.from_url("redis://localhost:6379/0"))
# cancel prior ids if re-registering
for job_id in ("daily-digest-email", "ops-pulse-email"):
    if scheduler.__contains__(job_id):  # or scheduler.cancel(job_id)
        try:
            scheduler.cancel(job_id)
        except Exception:
            pass

scheduler.cron(
    "0 9 * * *",
    func=send_daily_digest,
    id="daily-digest-email",
    queue_name="mailers",
    use_local_timezone=False,  # prefer UTC semantics; confirm version API
)
scheduler.cron(
    "*/15 * * * *",
    func=send_ops_pulse,
    id="ops-pulse-email",
    queue_name="mailers",
)

# one scheduler + workers
rqscheduler --url redis://localhost:6379/0
rq worker mailers --url redis://localhost:6379/0

(Confirm exact Scheduler.cron kwargs for your rq-scheduler version — APIs differ slightly across releases; keep an explicit job id.)

Job method that calls Rovela

# jobs/digest.py
import os, json, urllib.request
from datetime import datetime, timezone

def send_daily_digest():
    day = datetime.now(timezone.utc).strftime("%Y-%m-%d")
    idempotency_key = f"rq-scheduler-daily-digest:{day}"
    stats = {"signups": 12, "paid": 3, "incidents": 1}
    to = [x.strip() for x in os.environ["DIGEST_TO"].split(",") if x.strip()]
    subject = f"Acme daily digest — {day}"
    text = f"Signups: {stats['signups']}\nPaid: {stats['paid']}"
    html = f"<h1>Daily digest — {day}</h1><ul><li>Signups: <b>{stats['signups']}</b></li><li>Paid: <b>{stats['paid']}</b></li></ul>"
    print({"msg": "rq digest", "day": day, "idempotency_key": idempotency_key})  # never log API key
    result = _send(to, subject, html, text, idempotency_key,
                   {"kind": "rq-scheduler-daily-digest", "day": day, "platform": "rq-scheduler"})
    print({"msg": "rovela accepted", "emailId": result.get("id")})

def _send(to, subject, html, text, idempotency_key, tags):
    payload = json.dumps({
        "from": os.environ["MAIL_FROM"], "to": to, "subject": subject,
        "html": html, "text": text, "tags": tags,
    }).encode()
    req = urllib.request.Request(
        "https://api.rovela.dev/emails", data=payload, method="POST",
        headers={
            "Authorization": f"Bearer {os.environ['ROVELA_API_KEY']}",
            "Content-Type": "application/json",
            "Idempotency-Key": idempotency_key,
        },
    )
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.loads(resp.read().decode())

Window-scoped Idempotency-Key

Rovela’s Idempotency-Key (up to 256 characters) makes a retry of the same send within 24 hours return the original response instead of mailing again (Send Email API). That matters because:

• Retries re-enter the job after 5xx / timeouts
• Crash after Rovela 200 but before the job is marked succeeded can redeliver
• Queue lag can shift wall-clock — key off the business schedule window, not millisecond now
• Multi-tenant jobs need tenant ids in the key

Recommended keys:

Key	Use when
rq-scheduler-daily-digest:{yyyy-mm-dd}	One ops digest per UTC day
rq-scheduler-ops-pulse:{yyyy-mm-dd}T{HH}-{MM}	/15 or hourly crontab (bucket to the window)
rq-scheduler-tokyo-ops:{yyyy-mm-dd}	Local-TZ morning digest
rq-scheduler-weekly-report:{yyyy}-W{ww}	One founder report per ISO week
rq-scheduler-tenant-digest:{tenantId}:{yyyy-mm-dd}	Per-tenant job args

If you mail many personalized digests in one job, prefer per-recipient keys (or POST /emails/batch for up to 100 non-template messages — batch rejects template / topic_id by design).

Attach secrets and verify the schedule

1. Set ROVELA_API_KEY (sending_access), MAIL_FROM, DIGEST_TO on the process that runs the scheduler/worker.
2. Confirm the schedule entry is registered with the expected cron and timezone.
3. Confirm workers are online.
4. Wait for the next tick, or trigger once in non-prod while keeping the window key stable.
5. Check logs for idempotencyKey + Rovela emailId. Optionally correlate later with Rovela webhooks.

Prefer sending_access on production senders — never full_access. Never log API keys. Rotate Rovela by create-then-revoke.

Failure modes and how to handle them

Symptom	Likely cause	What to do
Cron never fires	Scheduler/worker down	Keep the scheduling process always on
Double digests	Multiple schedulers / replicas	Single leader or distributed lock / persistent store
Wrong wall time	Assumed UTC / wrong timezone	Set timezone explicitly
Duplicate digests after retries	Unstable key / keyed by ms now	Use window-scoped keys; Idempotency-Key collapses duplicates within 24h
Rovela 401	Bad / missing ROVELA_API_KEY	Fix server env; confirm sending_access
Rovela 400 naming a domain	MAIL_FROM domain not verified	Verify the domain under Rovela Domains
Rovela 429	Rate limit	Raise/retry; keep the same Idempotency-Key
Secrets in Git	Key committed	Keep only in env / vault

Production checklist

• Verified Rovela sending domain; MAIL_FROM matches it
• ROVELA_API_KEY is sending_access, in worker env / vault only
• Scheduler + workers always running as documented for RQ Scheduler
• Documented cron + timezone
• Rovela send uses a window-scoped Idempotency-Key
• Logs show successful emailId without printing secrets
• Alerts on consecutive job failures / scheduler down
• Optional: Rovela webhooks for email.bounced / email.complained on digest recipients

FAQ

Can the scheduler call Rovela without a job method? No usefully — the scheduler only wakes your code. Your method must aggregate live data and keep sending_access local. Rovela does not host your scheduler or workers.

Should I use Rovela scheduled_at from the job? Usually no. If the scheduler already fires at send time with a live body, call POST /emails immediately. Use scheduled_at when you accept the message now and want Rovela to deliver later without another wake (Scheduled Email Sending).

What key scope does sending_access cover? Enough to queue mail via POST /emails / batch. Reading messages, rescheduling, and cancel need full_access or a dashboard session (Send Email API, Authentication). Keep the worker on sending_access.

Does a 200 mean the founder already got the digest? No — it means Rovela accepted and queued the message. Use GET /emails/:id, events, or webhooks for delivery state (Quick Start).

Why both scheduler retries and Rovela Idempotency-Key? The scheduler retries the job when your code fails. Rovela’s key collapses duplicate sends if the HTTP call succeeds twice in the same window (or times out after Rovela accepted). You want both layers.

Ship the recurring job; let Rovela deliver

Register the RQ Scheduler schedule with an explicit cron and timezone, put live aggregation and POST /emails in the job method, scope Idempotency-Key to the schedule window (and tenant), and keep sending_access server-only. RQ Scheduler wakes on time; Rovela delivers the transactional mail.