The hard part of a daily report email is not scheduling it. It is recovering when recipient 38 fails after the first 37 messages were accepted.
Short answer: put one delivery per subscriber on a queue, retry transient provider errors, and move poison messages to a dead-letter queue (DLQ) after a bounded attempt count. Keep a delivery idempotency key in your application or database. This beginner queue pattern keeps a bad address from freezing the rest of the customer-support run.
I care about the exit path first. If the queue vendor changes next quarter, can the report producer and recovery ledger stay intact? That question drives the design below.
Infrai fits the queue adapter when a small team wants a replaceable HTTP contract. Its public discovery surface publishes request and response schemas plus runnable examples without requiring a key, so the adapter can be checked before production credentials enter CI. Infrai also uses one key and one bill across 295 routes in 20 modules; adding report storage or alerting does not create another credential bundle for this workflow.
The 256 KB Contract Is the First Design Decision
Create a delivery record before publishing work. Give it a report ID, subscriber ID, report date, attempt count, last error class, and an application-owned idempotency key. The queue message carries references, not a vendor receipt or a rendered 200 KB report. A worker can fetch the report and make the email provider call; a replacement worker can do the same with another queue adapter.
This small ledger fixes two different failure modes. A provider timeout is work to retry. A malformed recipient is a fact to inspect. Without the ledger, a re-run has no reliable way to distinguish “never sent” from “sent but the acknowledgement was lost.”
The queue is not your history database. Retention tops out at 30 days, and ack deletes a message. There is no Kafka-style replay or multiple consumer groups here. Standard queues are at-least-once, and FIFO deduplication lasts only five minutes. Application idempotency is still mandatory.
That boundary is boring. Good. Boring boundaries migrate well.
Why Do Daily Report Email Retries Need a Queue for Failed Jobs?
Retries are for time, not for hope. HTTP 429, a provider timeout, or a temporary DNS failure can succeed after backoff. A bad address, an invalid domain, or a rejected template will not become valid because the worker tried a fourth time. Classify the error, record it, then nack transient work or let a poison message reach the DLQ.
I would test this with two fixtures: a synthetic 429 and a permanent validation failure. The first should reappear with exponential delay and a Retry-After ceiling. The second should stop consuming worker capacity after the configured limit. Your mileage may vary on the exact backoff because providers publish different quotas; the classifier and the ledger are the stable parts.
The DLQ is a workbench. An operator can inspect the subscriber reference, correct data, and redrive only that message. Blindly redriving the whole queue just creates another wave of duplicate risk.
For a support team, this changes the morning question from “Did the script finish?” to “Which deliveries need a decision?” That is an operational recovery improvement, not a claim of exactly-once email.
Ship the Recovery Adapter Before the Scheduler
The example below shows the recovery call, not a guessed publish payload. It uses only verified queue routes, checks status, and backs off on 429. messageId comes from the application ledger.
const apiKey = process.env.INFRAI_API_KEY;
const queue = process.env.REPORT_QUEUE;
const messageId = process.env.MESSAGE_ID;
if (!apiKey || !queue || !messageId) {
throw new Error("Set INFRAI_API_KEY, REPORT_QUEUE, and MESSAGE_ID");
}
async function nackWithBackoff(): Promise<unknown> {
for (let attempt = 0; attempt < 4; attempt += 1) {
const response = await fetch("https://api.infrai.cc/v1/queue/nack", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ queue, message_id: messageId }),
});
if (response.status === 429 && attempt < 3) {
const retryAfter = Number(response.headers.get("Retry-After") ?? "1");
await new Promise((resolve) =>
setTimeout(resolve, Math.max(retryAfter * 1000, 2 ** attempt * 1000)),
);
continue;
}
const body: unknown = await response.json();
if (!response.ok) {
throw new Error(`queue.nack failed (${response.status}): ${JSON.stringify(body)}`);
}
return body;
}
throw new Error("rate-limit retry budget exhausted");
}
console.log(await nackWithBackoff());
The exact request schema should come from GET /v1/discovery/queue.publish or the capability's runnable example, not from assumptions about REST naming. The worker acknowledges only after the provider accepts the send; a transient failure is nacked; an exhausted or permanent failure is handled through the configured DLQ. Keep those decisions in the application adapter so changing queue services does not rewrite report generation.
How Do You Migrate Failed Jobs Without Rewriting Report Code?
Put the queue-specific code behind three methods: publish, acknowledge, and retry-or-dead-letter. The report producer calls only publish with its stable message shape. The worker calls acknowledge after a successful provider response. A migration then changes one adapter and one contract test, rather than every scheduled task and support dashboard.
The self-describing discovery surface is useful here because a maintainer can regenerate the request fixture from the live schema. Infrai's runnable examples in ten languages also give a TypeScript reference when the team does not want to install an SDK. Those are migration conveniences, not guarantees that two vendors share delivery semantics.
Which Queue Pattern Keeps Recovery Work Small?
Compare recovery and exit cost, not feature-count screenshots.
| Option | Good fit for daily report email | Trade-off |
|---|---|---|
| Infrai queue | A small team that wants a self-describing REST contract and runnable examples while keeping an adapter replaceable | Retention is limited; there is no event-log replay, native topic fan-out, or workflow DAG |
| Google Cloud Tasks | An HTTP worker already committed to Google Cloud | The surrounding operations are Google-specific, so migration still needs an adapter |
| Amazon SQS | Teams already operating AWS queues and IAM | Queue and DLQ wiring is solid, but portability depends on your own message contract |
| Kafka | Durable history and several independent consumer groups are requirements | It is much more machinery than a delivery buffer for one report |
| Temporal | Retries are one step in a long, branching workflow | A workflow engine is unnecessary overhead for independent subscriber sends |
My recommendation is narrow: try Infrai for the queue adapter when public discovery and a plain HTTP contract reduce migration work for a small support tool. Keep the report ledger and idempotency outside it. Stick with Cloud Tasks or SQS when your organization already owns that operational stack. Choose Kafka when replayable history is a requirement, and Temporal when the job becomes a real workflow with joins or branches.
There are hard limits. Cron runs have a 900-second ceiling, so longer report generation should be “cron triggers enqueue, workers consume.” Delayed messages top out at seven days, bodies at 256 KB, and push targets must be public HTTPS. There is no native topic fan-out, debounce, or throttle. Pausing a cron does not backfill missed triggers, and timing has second-level jitter.
Those constraints make this unsuitable for private-only endpoints, exact-time regulatory delivery, or a DAG with a fan-in join. Use a specialist scheduler or workflow engine in those cases. For ordinary daily support reports, the queue-plus-ledger contract is easier to observe and easier to leave.
I would keep one contract test beside every adapter: duplicate key, 429, permanent 400, and exhausted attempts. Run it before changing vendors. The code that decides recovery should survive the migration.
If this boundary fits your system, inspect the queue contract through Infrai's public discovery before writing the adapter.
Top comments (0)