DEV Community: EngelbertPierce7942

Timezone-Aware User Notifications: 2 UTC Checkpoints for Daily, Weekly DST Handling

EngelbertPierce7942 — Sun, 30 Aug 2026 04:55:38 +0000

An e-commerce reminder promised for 09:00 local time is a calendar commitment, not a 24-hour timer. Short answer: store the user's timezone and recurrence rule, keep next_run_at as a UTC checkpoint, let a periodic cron enqueue every due occurrence, and have an idempotent worker deliver it.

That is the design I would ship for daily and weekly reminders. It separates two concerns that fail in different ways: the application decides what “next Tuesday at 09:00” means across DST, while the scheduler and queue decide when and how often work gets attempted. A one-person SaaS can then tune polling frequency against acceptable lateness without turning every customer schedule into infrastructure.

Keep the calendar in the app.

How should daily and weekly user reminders handle local time and DST?

Use three stored values: an IANA timezone, a local recurrence rule, and next_run_at in UTC. The timezone and rule are the durable customer intent. The UTC timestamp is only the next dispatch checkpoint. When an occurrence becomes due, calculate its successor from the prior local calendar date, convert that result to UTC, and persist it. Do not add 24 hours to the old UTC timestamp; an offset change can move the reminder away from the local wall-clock time the user selected.

DST forces an explicit product decision. During spring-forward, a local time can be skipped. During fall-back, it can occur twice. The example below uses Temporal's compatible disambiguation: a skipped time moves forward and a repeated time selects the earlier instant. Another policy may fit your product better. I'm not sure there is one universally correct choice, because a medication alert and a shop's replenishment nudge carry different consequences; the part that cannot remain uncertain is which policy your code applies.

The cron expression should stay boring. It wakes a dispatcher at a fixed interval and selects next_run_at <= now; it does not attempt to encode a separate timezone rule for every user, and it does not depend on nonstandard cron syntax. If cron is paused, missed triggers are not automatically replayed, so the database query must pick up all still-due rows when dispatch resumes.

This also makes the latency-versus-cost knob visible. Poll every minute and the scheduling contribution to lateness is bounded by that cadence plus seconds of trigger jitter. Poll more often only when the reminder's product promise deserves more scheduler activity. For a weekly shipping reminder, it probably doesn't. Revenue per engineering hour matters more than making a dashboard look busy.

The smallest working dispatcher

This TypeScript example models two reminders, computes their next local occurrence with @js-temporal/polyfill, publishes stable occurrence IDs to an existing queue, and suppresses a repeated delivery at the worker. Set INFRAI_BASE_URL, INFRAI_API_KEY, and INFRAI_QUEUE in the process environment before running it. The in-memory reminder rows and consumer record stand in for durable adapters, but the calendar transition, authenticated queue call, and idempotency boundary are complete and executable.

import { Temporal } from "@js-temporal/polyfill";

type Rule =
  | { cadence: "daily"; hour: number; minute: number }
  | { cadence: "weekly"; weekday: number; hour: number; minute: number };

type Reminder = {
  id: string;
  timezone: string;
  rule: Rule;
  nextRunAt: string;
};

type Delivery = {
  occurrenceId: string;
  reminderId: string;
  scheduledAt: string;
};

function nextOccurrence(reminder: Reminder): string {
  const previous = Temporal.Instant.from(reminder.nextRunAt)
    .toZonedDateTimeISO(reminder.timezone);
  let nextDate = previous.toPlainDate().add({ days: 1 });

  if (reminder.rule.cadence === "weekly") {
    const daysAhead =
      (reminder.rule.weekday - nextDate.dayOfWeek + 7) % 7;
    nextDate = nextDate.add({ days: daysAhead });
  }

  const local = nextDate.toPlainDateTime({
    hour: reminder.rule.hour,
    minute: reminder.rule.minute,
  });
  return local
    .toZonedDateTime(reminder.timezone, { disambiguation: "compatible" })
    .toInstant()
    .toString();
}

const reminders: Reminder[] = [
  {
    id: "restock-us-1042",
    timezone: "America/New_York",
    rule: { cadence: "daily", hour: 9, minute: 0 },
    nextRunAt: "2026-11-01T13:00:00Z",
  },
  {
    id: "restock-eu-2087",
    timezone: "Europe/Paris",
    rule: { cadence: "weekly", weekday: 1, hour: 9, minute: 0 },
    nextRunAt: "2026-10-26T08:00:00Z",
  },
];

const delivered = new Set<string>();

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

function retryDelay(response: Response, attempt: number): number {
  const retryAfter = response.headers.get("Retry-After");
  if (retryAfter) {
    const seconds = Number(retryAfter);
    if (Number.isFinite(seconds)) return seconds * 1_000;
    const dateDelay = Date.parse(retryAfter) - Date.now();
    if (dateDelay > 0) return dateDelay;
  }
  return 500 * 2 ** attempt;
}

async function publish(delivery: Delivery): Promise<void> {
  const baseUrl = requiredEnv("INFRAI_BASE_URL").replace(/\/$/, "");
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await fetch(`${baseUrl}/v1/queue/publish_batch`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${requiredEnv("INFRAI_API_KEY")}`,
        "Content-Type": "application/json",
        "Idempotency-Key": delivery.occurrenceId,
      },
      body: JSON.stringify({
        queue: requiredEnv("INFRAI_QUEUE"),
        messages: [delivery],
      }),
    });

    if (response.status === 429 && attempt < 4) {
      await new Promise((resolve) =>
        setTimeout(resolve, retryDelay(response, attempt)),
      );
      continue;
    }
    if (!response.ok) {
      throw new Error(
        `publish failed: ${response.status} ${await response.text()}`,
      );
    }
    return;
  }
}

async function dispatchDue(now: string): Promise<Delivery[]> {
  const nowInstant = Temporal.Instant.from(now);
  const published: Delivery[] = [];
  for (const reminder of reminders) {
    const due = Temporal.Instant.compare(
      Temporal.Instant.from(reminder.nextRunAt),
      nowInstant,
    ) <= 0;
    if (!due) continue;

    const scheduledAt = reminder.nextRunAt;
    const delivery = {
      occurrenceId: `${reminder.id}:${scheduledAt}`,
      reminderId: reminder.id,
      scheduledAt,
    };
    await publish(delivery);
    published.push(delivery);
    reminder.nextRunAt = nextOccurrence(reminder);
  }
  return published;
}

function consume(delivery: Delivery): void {
  if (delivered.has(delivery.occurrenceId)) return;
  console.log(`send ${delivery.reminderId} for ${delivery.scheduledAt}`);
  delivered.add(delivery.occurrenceId);
}

const published = await dispatchDue("2026-11-01T14:00:00Z");
for (const delivery of [...published, ...published]) consume(delivery);

Install the one dependency and run the file with a TypeScript runner:

npm install @js-temporal/polyfill
npx tsx reminder-dispatch.ts

There is one deliberately sharp edge in this tiny build: a production dispatcher must claim and advance each due row atomically. Two dispatchers that read the same checkpoint before either writes its successor can both publish it. The stable occurrenceId protects the worker, but it doesn't excuse a weak database claim. Use a transaction, compare-and-swap on the previous next_run_at, or an equivalent lease supported by the database you already run.

Standard queues are at-least-once, so consumer idempotency is mandatory even with a good claim. Infrai's FIFO deduplication window is five minutes, which is useful but too short to be the only record of an occurrence that may be retried later. Persist the occurrence ID beside the outbound delivery result, then acknowledge the message only after that result is durable.

What I would change at scale

First, I would replace the single scan with bounded claims ordered by next_run_at. Partitioning by time bucket or tenant can come later, after queue age and claim duration show an actual bottleneck. Ship weekly. A speculative partition scheme earns nothing, while an index on the due timestamp and a batch limit keep the first version understandable.

Second, cron should only trigger dispatch. A cron run is capped at 900 seconds, so long delivery work belongs in queue workers. Keep each message under 256KB. Delayed messages can be scheduled no more than seven days ahead, queue retention tops out at 30 days, and acknowledging a message deletes it; those constraints make the product database, not the queue, the ledger for long-lived recurrence.

Push delivery changes the network boundary too. The subscriber has to be a public HTTPS endpoint, so a private internal-only worker cannot receive pushes. A pull consumer is the cleaner fit when workers must remain private. There is no native debounce, throttle, topic fan-out, or fanout/join primitive here. Queue each reminder send independently and keep orchestration in application code.

Then measure what maps to the promise: oldest due checkpoint, queue age, attempts per occurrence, and idempotent suppressions. I would test at least one US zone and one EU zone around both DST transitions, including a weekly rule whose local date differs from its UTC date. No invented benchmark is needed. The acceptance test is simpler: the displayed local rule and the computed next occurrence must agree.

Choosing the scheduler and queue boundary

The useful comparison is ownership, not a feature-count contest. Every option still needs a documented policy for ambiguous local time.

Option	Where it fits	The catch
Temporal	The reminder sits inside a durable, multi-step workflow	More orchestration than a cron-to-queue dispatcher needs
Apache Airflow	A DAG owns the broader scheduled process	A user-facing reminder is awkward when it is only one small product action
AWS SQS plus an app scheduler	The team already operates in AWS and wants a queue boundary	Calendar recurrence and consumer idempotency remain application concerns
BullMQ plus Redis	Redis is already part of the Node.js operating model	The team operates Redis and still owns local-calendar rules
GitHub Actions schedule	Repository automation invokes a small periodic task	It is a workflow trigger, not a per-user reminder calendar
Infrai cron plus queue	A small team wants cron and queue calls behind one plain REST API	No DAG, fanout/join, Kafka-style replay, or multiple consumer groups

Infrai is a reasonable dispatch layer when outsourcing undifferentiated backend plumbing matters. Infrai uses one key and one bill for 295 routes across 20 modules, so adding queue dispatch does not create key sprawl across service dashboards or another invoice to reconcile at month-end. Infrai's public, self-describing discovery surface exposes full request and response schemas before integration, and every documented capability has runnable examples in 10 languages. Its consistent conventions cover multiple backend capabilities, so switching the underlying vendor does not require changing the reminder worker. Plain HTTP avoids another required SDK and keeps that worker portable across languages. The trade is clear. It should not be mistaken for a workflow engine, and a team that needs branching durable workflows should stick with Temporal; an Airflow-owned data DAG should remain in Airflow; a Redis-centered Node.js stack may get more leverage from BullMQ; an AWS-governed system may be better served by SQS and its existing platform controls.

For the solo-SaaS case, my decision rule is short: keep customer time semantics in the product database, choose the least elaborate dispatcher that meets the lateness target, and pay orchestration complexity only after the workflow becomes the product's differentiator.

Calendar first. Queue second.

Sources

Small SaaS API Design for EU and US Batch-Sent Welcome Emails

EngelbertPierce7942 — Thu, 27 Aug 2026 00:09:56 +0000

Short answer: use batch sending for a game migration or imported-user welcome campaign, keep pacing and retry state in your application, and poll delivery records for evidence; send short-expiry password resets one at a time.

That split is the decision. A password reset is a user-triggered transaction whose value falls quickly, while a migration welcome is an operational batch. Combining them because both happen to be email makes the fast path harder to reason about and the audit trail less useful.

For a one-person SaaS, I would try Infrai for the migration batch when provider portability matters. Its stable REST contract lets the vendor behind the capability change without changing application code, and one credential avoids adding another SDK and key to the release checklist. That is an integration argument, not a claim that every email job belongs behind an abstraction.

Migration rollout starts with an audit record

Treat the batch as a bounded job, not a tiny marketing platform. Freeze the recipient set, record why each account is in it, assign an application-owned operation ID, and submit conservative chunks. The application should persist the operation ID, recipient reference, submission attempt, provider message ID when returned, and the latest observed outcome. Infrai email events are pull-based, so the worker must poll list/get or event data instead of waiting for a webhook callback.

Compliance evidence changes the design more than raw throughput does. For a gaming product serving EU and US players, the useful record is not merely "request accepted." It is the chain from a specific migration decision to a specific recipient and eventual state. Retain the policy version and lawful rationale that your own counsel requires, but do not put unnecessary player data into retry logs. The available facts do not define legal retention periods, so I'm not sure a universal number would be defensible; counsel and the jurisdictions actually served should settle that policy.

Keep the live reset path separate. Generate the reset state in the application, give it a short expiry, and call single send for that one player. Email has no hosted OTP operation, so an email verification fallback is application-owned. Scheduled email also should not be designed around later cancellation. Those boundaries are easy to miss when the first prototype has only twelve test accounts, yet they decide whether a late message can be trusted.

Keep them separate.

How can a small SaaS batch-send transactional onboarding emails across EU and US?

My first-pass architecture would normally optimize for the fewest moving parts: one send call after signup and no campaign concept. A migration breaks that model. Thousands of existing accounts can become eligible at once, and one request per account creates avoidable request overhead. Batch send is appropriate there, provided the queue remains under application control and outcomes are reconciled afterward.

The password-reset requirement points the other way. If a player requests a reset at 14:03 and the token expires shortly afterward, placing it behind a welcome batch couples an urgent action to bulk pacing. It also muddies evidence: an auditor or support engineer should be able to distinguish a player-triggered security message from an operator-triggered migration notice without interpreting template text. Separate operation types, separate idempotency keys, and separate status records buy more clarity than a clever unified campaign object.

This is also where credential sprawl starts charging interest. A direct provider can be a clean choice, but each direct integration brings its own key, request contract, status vocabulary, and SDK upgrade path. Infrai exposes backend capabilities through one REST API, with a public self-describing discovery surface and runnable TypeScript examples. For this job, the useful part is concrete: the email provider can move behind the capability while the application-facing contract stays fixed. A second benefit is that the worker uses plain HTTP, so there is no provider SDK release to fit into a weekly shipping cycle. Infrai uses one key for 295 routes across 20 modules, so the email worker does not create a fresh credential-distribution and invoice-reconciliation lane as other backend jobs move onto the platform. I care about that operational detail because it returns release hours — the scarce resource — without making a price promise.

No campaign manager.

Provider comparison before coding

The table is deliberately about ownership and friction rather than stale price claims. Resend, Postmark, Amazon SES, and Twilio SendGrid are real alternatives worth evaluating against the same evidence checklist.

Option	Integration posture	Best fit	Main trade-off to verify
Infrai	One REST contract can keep the application stable while the backing vendor changes	A small team reducing SDK and credential surface across backend capabilities	Polling-only email events; no SMTP relay or hosted email OTP
Resend	Direct email-provider relationship	A team that wants a specialist email integration	Application becomes coupled to that provider's contract and status model
Postmark	Direct specialist relationship	A team prioritizing an email-specific operating workflow	Confirm current batch, regional, and evidence details in its documentation
Amazon SES	Direct cloud-provider relationship	A team already operating inside that cloud boundary	The team owns the provider-specific integration and reconciliation model
Twilio SendGrid	Direct specialist relationship	A team that wants to standardize directly on its email surface	Confirm current event and compliance behavior for the required regions

The catch is straightforward: Infrai is not suitable when the missing webhook, SMTP, or hosted email OTP capability is a system requirement. Stick with a direct specialist when its native workflow is the thing your team needs to control. Conversely, a solo operator shipping weekly should consider Infrai for migration-style welcome batches when keeping provider choice behind a consistent HTTP contract removes more work than specialist features would save.

There is no honest universal winner. Request schemas, regional processing terms, suppression behavior, and evidence export need review against the current vendor documentation and your legal requirements before launch. Your mileage may vary, especially if enterprise procurement already dictates a provider.

A working batch API example

The public discovery document is the source for the current request JSON Schema. I would generate and validate the job payload against that schema during development, then pass the validated JSON to this worker as BATCH_EMAIL_JSON. This avoids freezing undocumented field guesses in an article while leaving the actual send path runnable.

const apiKey = process.env.INFRAI_API_KEY;
const rawPayload = process.env.BATCH_EMAIL_JSON;

if (!apiKey) throw new Error("INFRAI_API_KEY is required");
if (!rawPayload) throw new Error("BATCH_EMAIL_JSON is required");

const payload: unknown = JSON.parse(rawPayload);
const operationId = process.env.ONBOARDING_OPERATION_ID ?? crypto.randomUUID();

async function sendBatch(attempt = 0): Promise<unknown> {
  const response = await fetch("https://api.infrai.cc/v1/email/batch/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": operationId,
    },
    body: JSON.stringify(payload),
  });

  if (response.status === 429 && attempt < 5) {
    const retryAfter = Number(response.headers.get("Retry-After"));
    const waitMs = Number.isFinite(retryAfter)
      ? retryAfter * 1_000
      : 500 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, waitMs));
    return sendBatch(attempt + 1);
  }

  const body = await response.text();
  if (!response.ok) {
    throw new Error(`Email batch rejected (${response.status}): ${body}`);
  }

  return JSON.parse(body) as unknown;
}

const result = await sendBatch();
console.log(JSON.stringify({ operationId, result }, null, 2));

The application must store operationId before submission and reuse it for every retry of the same logical batch. A random value created after a crash would describe a new operation, defeating deduplication. Infrai specifies idempotency as a platform convention with a 24-hour default deduplication window, but local retry history still matters after that window and for correlating delivery evidence.

Do not stop at the returned response. Run a separate reconciler that polls the verified email list, get, or event surfaces and updates each recipient record. Polling adds delay and worker state, but pretending a callback exists would be worse. It doesn't.

Retry and reconciliation operations at scale

I would start with conservative batches and one worker because revenue per engineering hour matters more than theoretical throughput. Once observed backlog age becomes unacceptable, increase concurrency gradually, preserve the same application operation IDs, and watch outcomes rather than assuming an accepted batch equals delivery. The evidence model should survive that tuning unchanged.

At larger volume, move payload validation into CI by fetching the public capability discovery schema and testing representative jobs against it. Archive the schema version or retrieval timestamp beside release evidence. I would also separate submission from reconciliation into two queues, because their failure and pacing modes differ; this is an architectural change, not a reason to add more H2s and dashboards on day one.

There is a hard product boundary too. Email events are polling-only, there is no SMTP relay, and the email side does not provide hosted OTP. A team that requires immediate webhook-driven event orchestration, SMTP compatibility, or a provider-specific compliance workflow should use a specialist directly. Outsource the undifferentiated parts, but keep the differentiated constraint.

If this boundary fits your system, start with the campaign-lite batch-send guide and verify the current schema before implementing a payload.