Keep receipt templates under a versioned release owner, and make each retry reuse the content approved for the settled payment. TL;DR: log the failed stage, preserve the template revision, and retry only when the evidence supports another submission. For an e-commerce receipt, the deciding constraint is who can change the message between payment settlement and its eventual delivery.
A retry that silently picks up a template edit can send a different receipt from the one the payment workflow authorized. A successful API response also needs its own evidence boundary: record what the response establishes, then track later delivery evidence separately. This decision record uses template change control as the lens for failed email deliveries, error logging, and API retry strategies.
Who owns the receipt when an email attempt fails?
Assign three responsibilities explicitly: the receipt owner approves content, the application owner fixes rendering inputs, and the delivery owner decides whether a failed submission can be repeated. One team can hold all three responsibilities. The separation matters because a delivery retry cannot repair a missing order total, and a copy edit cannot establish whether a timed-out submission was accepted.
For this design, a receipt is eligible only after payment settles. The example order, order_4821, has an illustrative settled total of 7400 USD cents. Its receipt intent binds that settlement to template revision receipt_r7, locale en-US, and a restricted snapshot of the receipt fields. These are example values and proposed application policies, not an external API contract. A later edit to the active template creates a new revision; it does not alter this pending intent.
Freeze the intent.
That rule has a cost: a corrected template does not automatically fix queued receipts. The content owner must authorize a replacement revision and record why pending intents should migrate. For a financial message, this review makes a content change visible instead of hiding it inside an operational retry.
How should error logging guide retry decisions for failed email receipts?
Use three template ownership rules: approve a revision before release, bind it to the receipt intent, and require an explicit migration for pending messages. Keep the rendered subject and body, or the immutable revision plus its exact input snapshot, in restricted storage. A template name alone is insufficient for this design because the active content behind that name could change.
The receipt intent and the submission attempt are different records. The intent identifies the settled payment and approved content. Each attempt records its own sequence number, stage, outcome, and next action. Enforce a unique intent key for the chosen settlement event in persistent storage; repeated payment notifications should resolve to that intent. A worker also needs an atomic claim so two workers cannot independently consume the same due attempt. These are application invariants, not claims of exactly-once delivery.
Log enough to answer a concrete question: did this attempt fail before submission, receive an explicit rejection, or lose certainty after the request left the worker? Recommended fields are intent_id, attempt, template_revision, stage, outcome, reason_code, request_id, and next_action. Add elapsed time and a correlation identifier where available. Keep recipient addresses, rendered receipt bodies, credentials, and raw responses containing customer data out of ordinary operational logs. Access rules and retention periods should follow the organization's requirements; an error log should not become a second receipt database.
Uncertainty needs a state. Name it explicitly.
A local rendering failure belongs to the application owner and should stop automatic submission until the input or approved revision is repaired. An explicit temporary rejection can enter a bounded retry schedule under the delivery policy. A definitive permanent rejection should stop that intent. A timeout after submission requires reconciliation against available request evidence before another attempt; blindly treating it as a confirmed failure creates a duplicate-send path.
Authentication deserves its own reason code. SPF authorizes hosts for the SMTP identities described in RFC 7208; it does not validate a receipt's financial content or promise inbox placement. The RFC distinguishes temperror, a transient evaluation error, from permerror, an error requiring intervention, in Sections 2.6.6 and 2.6.7. Preserve those distinctions when the delivery evidence exposes them. Don't translate every authentication problem into a generic retryable failure, and don't infer an SPF result from a timeout.
Decision: compare ownership before choosing a retry mechanism
The following table compares proposed operating models. It describes responsibilities and trade-offs, not capabilities promised by a particular service.
| Ownership model | What the receipt intent preserves | How a repair reaches pending receipts | Main trade-off |
|---|---|---|---|
| Application release owns templates | Immutable revision and input snapshot | Reviewed application migration | Strong release traceability; copy changes require release coordination |
| Content team owns immutable revisions | Approved revision identifier and input snapshot | Explicit approval and migration | Faster editorial changes; approval and rollback become shared operations |
| Content team edits one active template | Template name unless the application also snapshots content | The next render uses the edit | Simple editing; replay can change unless content is frozen separately |
Choose the first model for this receipt workflow when the backend team owns the payment-to-receipt contract. The second is equally defensible when content editors need independent releases and can publish immutable, approved revisions. The actual decision is whether a failed message can be reconstructed and whether somebody owns the authority to change it.
Account for operational cost as well. Frozen receipt content needs protected storage; revision-only storage needs dependable retention of both templates and inputs. Longer retry windows retain more pending work and require more reconciliation capacity. Those costs belong in the design review, alongside the human cost of coordinating a template correction.
Critical path: schedule from classified evidence
This Python example implements the scheduling decision after a worker has captured evidence. The three delays, 30, 120, and 600 seconds, are illustrative policy choices. They allow three automatic retries after the initial attempt; they are not service limits or a universal recommendation.
from dataclasses import dataclass from typing import Literal Outcome = Literal[ "accepted", "temporary", "permanent", "unknown", "render_error" ] @dataclass(frozen=True) class ReceiptIntent: intent_id: str order_id: str template_revision: str locale: str total_cents: int currency: str @dataclass(frozen=True) class Evidence: outcome: Outcome stage: str reason_code: str request_id: str | None = None RETRY_DELAYS_SECONDS = (30, 120, 600) def decide( intent: ReceiptIntent, attempt: int, evidence: Evidence ) -> dict[str, object]: if attempt < 1: raise ValueError("attempt must start at 1") action = { "accepted": "await_delivery_evidence", "permanent": "stop", "unknown": "reconcile", "render_error": "repair_content", "temporary": "review_exhausted", }[evidence.outcome] delay = None if evidence.outcome == "temporary": if attempt <= len(RETRY_DELAYS_SECONDS): action = "schedule_retry" delay = RETRY_DELAYS_SECONDS[attempt - 1] return { "intent_id": intent.intent_id, "template_revision": intent.template_revision, "attempt": attempt, "stage": evidence.stage, "outcome": evidence.outcome, "reason_code": evidence.reason_code, "request_id": evidence.request_id, "next_action": action, "delay_seconds": delay, } receipt = ReceiptIntent( intent_id="receipt_settlement_4821", order_id="order_4821", template_revision="receipt_r7", locale="en-US", total_cents=7400, currency="USD", ) record = decide( receipt, attempt=1, evidence=Evidence( outcome="temporary", stage="submission", reason_code="explicit_temporary_rejection", ), ) assert record["next_action"] == "schedule_retry" assert record["delay_seconds"] == 30 The function deliberately takes classified evidence. The submission adapter must map its documented responses into these categories; an exception message containing the word “temporary” is not a classifier. An accepted submission stays in await_delivery_evidence, and missing follow-up evidence should trigger investigation rather than an automatic resend. A later delivery event can produce a new decision only after correlation to the same intent and attempt.
This is a policy function, not a complete delivery worker. Persist its result with the attempt transition and the due retry in one database transaction. A scheduler consumes due work, applies any configured rate limits, and uses randomized delay within the permitted retry window to spread simultaneous retries. Where a submission interface documents idempotency, preserve its key according to that contract; otherwise, reconciliation must carry the uncertainty until available request evidence establishes whether the original submission was accepted or the delivery owner explicitly authorizes another attempt. Set an explicit receipt deadline as part of policy, too. Exhausting the attempt budget or reaching that deadline should create an owned review task.
Before deployment, test a missing template variable, a changed active revision, an explicit temporary rejection, and a timeout after the request is sent. Include duplicate settlement events and out-of-order delivery evidence. Verify that the pending receipt retains receipt_r7, that uncertainty does not enqueue an immediate resend, and that the fourth failed attempt reaches review. Test the boundary, not just the happy path.
During rollout, watch rendering failures by revision, retry exhaustion by reason code, the age of unresolved submissions, and accepted attempts without subsequent delivery evidence. Those views route work to the correct owner. A single “email failed” counter cannot distinguish a broken receipt release from a delivery problem, which is precisely the distinction this design needs.
Rejected option: render the latest template on every retry
Reject this option for settled-payment receipts because it lets a content edit change a pending financial message without an explicit migration. It also weakens error investigation: the version visible during debugging may differ from the one used by the failed attempt.
It has a valid use case. For an informational notice whose approved policy explicitly prefers the latest wording, rendering the active template on each attempt can reduce editorial coordination. Even there, record the revision actually rendered for every attempt. Preserve that evidence.
For receipts, the decision remains straightforward: preserve the approved content, classify failures at their actual boundary, and make uncertain submission outcomes visible before retrying. Template ownership determines who can repair a message; evidence determines whether sending it again is justified.
References
- RFC 7208: Sender Policy Framework (SPF), especially Sections 2.6.6 and 2.6.7 on evaluation errors: https://datatracker.ietf.org/doc/html/rfc7208