A SaaS user reminder scheduling API should store mutable property-management intent in a due table, then feed email, SMS, and push jobs into a rate-limited queue; cron alone can wake work, but it cannot prove that a tenant received anything.
| Design | Source of truth | Failure recovery | Best fit | Main catch |
|---|---|---|---|---|
| Cron sweep | Reminder rows in a database | Next sweep finds due rows again | Small workloads with relaxed timing | Repeated scans and duplicate claims need control |
| Delayed message | Broker state | Redelivery and dead-letter handling | High event volume with bounded delay | Long-horizon edits and cancellation can get awkward |
| Due table plus ready queue | Database before due time, queue after claim | Lease expiry, redelivery, and reconciliation | Property reminders across constrained channels | More moving parts and two observable stages |
Short answer: for user reminders sent through a rate-limited pool, keep future intent in a due table, claim it with a short lease, and enqueue only ready work. Let workers deliver email, SMS, or push with an idempotency key. This gives the best delivery evidence without pretending that cron or a queue can prove receipt.
The recommendation is deliberately boring. Use the database for mutable calendar intent and a queue for backpressure. A lease makes crashed claims recoverable; a stable delivery key makes repeats harmless at the application boundary. Then record every attempt separately from the reminder itself.
Keep it boring.
How should a SaaS reminder scheduling API handle email, SMS, and push?
Start by naming the guarantees. A reminder API accepts intent. A scheduler decides when that intent becomes eligible. A queue moves eligible work. A channel adapter attempts delivery. Those are four different promises, and folding them into one scheduled flag makes operations look cleaner than they are.
For a property manager, a lease-expiry notice may be edited after a tenant renews, while a maintenance-window alert may fan out to hundreds of residents. The former needs cheap cancellation and a clear current state. The latter needs controlled throughput. A future row handles edits well; a ready queue absorbs the burst without asking the database sweeper to wait behind slow channel calls.
Use at-least-once processing as the working assumption. A worker can finish the external call and lose its acknowledgement, so the same job may return. Exactly-once delivery is not a useful API promise here — the scheduler does not control the channel provider or the recipient's device. What it can control is a stable key such as propertyId:reminderId:channel:revision, plus an atomic record showing whether that revision has already been accepted for delivery.
This distinction is small on a diagram and huge at 09:00, when every building's daily reminder becomes due. Don't make the scheduler call providers directly. It should claim, enqueue, and get out.
Delivery guarantees come from state transitions
The state machine needs more precision than pending and sent. I use names such as scheduled, claimed, ready, attempting, accepted, retryable, and terminal. Accepted means the channel adapter accepted the request; it does not mean a human read it. Keep provider receipts or later delivery events as separate evidence.
A claim should carry a lease token and expiry. The dispatcher selects due rows, changes them from scheduled to claimed in the same database transaction, and commits before publishing ready jobs. After publication it records ready. If it stops between commit and publish, a reconciler can reclaim expired leases. If it publishes and stops before recording ready, the queue may contain a duplicate. The delivery key handles that branch. This is why the hybrid has two recovery mechanisms: leases repair missing queue messages, while idempotency absorbs repeated ones. Neither substitutes for the other. Dead-letter queues become useful after a message crosses the retry threshold: they isolate repeatedly failing work for inspection or redrive rather than cycling it forever, but they are not an archive and they don't explain the failure by themselves. Store structured attempt data — reminder ID, revision, channel, attempt number, eligibility time, claim token, adapter outcome, and correlation ID — while keeping message content and tenant contact data out of logs.
One sharp edge: preserve ordering only where the product requires it. A cancellation or corrected notice must not be overtaken by an older revision. Unrelated tenants do not need a global order, which would turn one slow job into a building-wide traffic jam. Compare revisions at delivery time and discard superseded work as a successful no-op.
The clock needs an explicit policy too. Store an absolute instant for dispatch and retain the user's time zone plus the rule that produced it. Recalculate future rows when the user edits that rule. Cron is good at recurring activation, but its traditional schedule describes recurring wall-clock times; it is not a per-recipient delivery ledger.
A compact TypeScript boundary
Keep the scheduling API small. Config bloat usually starts when transport settings, retry policy, tenant time zones, and provider credentials all leak into one request. The caller should submit reminder intent. Operations policy belongs behind the boundary.
type Channel = "email" | "sms" | "push"; type ReminderIntent = { reminderId: string; propertyId: string; recipientId: string; dueAt: string; revision: number; channels: Channel[]; template: string; }; type ReadyJob = { deliveryKey: string; reminderId: string; revision: number; channel: Channel; correlationId: string; }; interface ReminderStore { claimDue(now: Date, limit: number, leaseMs: number): Promise<ReminderIntent[]>; markReady(reminderId: string, revision: number): Promise<void>; } interface ReadyQueue { publish(job: ReadyJob): Promise<void>; } const keyFor = (item: ReminderIntent, channel: Channel): string => `${item.propertyId}:${item.reminderId}:${channel}:${item.revision}`; async function dispatchDue( store: ReminderStore, queue: ReadyQueue, now: Date, ): Promise<number> { const due = await store.claimDue(now, 200, 30_000); for (const item of due) { for (const channel of item.channels) { await queue.publish({ deliveryKey: keyFor(item, channel), reminderId: item.reminderId, revision: item.revision, channel, correlationId: crypto.randomUUID(), }); } await store.markReady(item.reminderId, item.revision); } return due.length; } The values 200 and 30_000 are sample controls, not universal defaults. Benchmark them against the database, queue, and strictest channel allowance. I care about four measurements: claim latency, oldest-ready-job age, attempts per accepted delivery, and terminal outcomes by channel. Throughput alone can look healthy while one tenant's reminder sits behind a hot property.
Workers should take capacity from a channel-specific limiter before calling the adapter. A shared pool with separate email, SMS, and push budgets can use spare concurrency without letting a burst on one channel consume every slot. On a retryable outcome, add jittered delay and preserve the same delivery key. On a terminal outcome, record it once and stop. The exact classification depends on the adapter contract; I'm not sure a generic library can choose it correctly without application-specific policy. Tests should pin that contract.
Measure the tail.
Test the ugly boundaries with a fake clock and deterministic adapters: a crash after claim, a crash after publish, two dispatchers racing for the same row, a revision change while a job waits, exhausted channel capacity, and redrive from the dead-letter queue. Run a load test with a deliberately tiny allowance — for example, five concurrent sends — and check oldest-job age, not just average throughput. Fast averages hide starvation.
When is the runner-up better?
Stick with a cron sweep when the reminder set is small, a few minutes of timing drift is acceptable, and the team already operates a transactional database. It has the shortest time-to-first-call and the least infrastructure. The catch is that scanning, claiming, retrying, and deduplicating are still your job; cron only starts the sweep.
Choose delayed messages as the source of truth when reminders are short-lived, rarely edited, and the broker's supported delay and retention behavior match the product requirement. This can remove the dispatcher and its due-row index. It is not suitable when users frequently reschedule far-future reminders or when product support needs a simple query for every pending notice. Your mileage may vary because broker semantics differ; verify maximum delay, retention, redrive, ordering, and cancellation before committing.
The hybrid is also a poor fit for a tiny service with one daily digest and no burst problem. Two stages mean two dashboards, a reconciler, and more deployment surface. Start with the cron sweep there. Move to the hybrid when worker saturation, edit volume, or recovery evidence becomes a measured problem.
No option makes multi-channel delivery exactly once. Pick the smallest design that keeps intent recoverable, constrains the worker pool, and leaves evidence an operator can trust.
