Skip to content

0012. Unknown send outcomes and metering at provider acceptance

  • Status: Accepted
  • Date: 2026-11-08

ADR 0007 forbids an unconditional resend after an unknown outcome. Amazon SES, the email provider (ADR 0024), has no idempotency key and no status lookup. The only way to learn whether SES accepted a message after a lost response is its event stream. HTTP clients for AWS retry automatically by default (AWS SDK v3 maxAttempts 3; aws4fetch retries 10), which would resend after a lost response without the store knowing.

Sending:

  • Automatic retries in the AWS client are disabled. adapters/email-ses uses aws4fetch with retries: 0 (it must run on both targets, ADR 0018); any AWS SDK client elsewhere uses maxAttempts: 1 for side-effecting calls.
  • A timeout, connection reset, or unparseable response is unknown. Only a definite pre-acceptance error is retried, by the store (ADR 0011).
  • attempt_id is persisted before the send call. Every send is tagged with project_id, message_id, and attempt_id.
  • Both SES configuration sets publish Send, Reject, Bounce, Complaint, Delivery, DeliveryDelay, and RenderingFailure events.
  • The provider message ID is bound to the message atomically on the first event or response that carries it; later events must match it.

Resolving unknown outcomes:

  • An unknown message waits up to 72 hours after the attempt for a Send event carrying its tags; the store registers a wake at that deadline (ADR 0011). A Send event resolves it to accepted.
  • After 72 hours without one, it is terminal failed:outcome_unknown: never resent, not billed, counted on an operator alert metric.
  • Late events always update suppression, even after 72 hours. A Send event after 72 hours leaves the message in failed:outcome_unknown for the run, records the late acceptance on the message and in its step log (so “was it sent?” is answered truthfully), and alerts.

Metering:

  • Billing has one rule: a message is billable when SES’s Send event for it arrives. A successful send response moves the message to accepted and binds the provider message ID, but writes no ledger row; the ledger row is written by the Send event. Bounced messages count.
  • A message that SES drops because the address is on its suppression list (a Bounce whose subtype names an SES suppression list) is not billable: the bounce writes a reversal for that message’s ledger row, so exported totals exclude it. Amended by ADR 0034: more drops write the reversal; see its amendment of 2026-11-15, decided by the maintainer. A reversal cancels only an existing charge (ADR 0034, Events).
  • Pre-send blocks (eligibility, suppression, plan limit, kill switch) and unresolved unknowns are not billed.
  • A Send event that arrives more than 72 hours after the attempt is not billed, but is still applied to suppression and raises an alert.
  • The usage ledger lives in the project store with at most one charge row and one reversal row per message (unique on (message_id, kind)), so a duplicate event or retry cannot count twice. It is exported to D1 with a per-project watermark of restore generation and sequence, and D1 deduplicates on (message_id, kind), so neither a repeated export nor an export after a restore can double-count (ADR 0010).
  • Test runs are not metered.
  • A contract test covers “SES accepted, then the connection reset”: the message becomes unknown, is not resent, and resolves from the Send event.
  • Details the metering side of ADR 0014, which superseded ADR 0001; events are counted for the event cap in ADR 0013.
  • If a later provider offers idempotency keys or status lookup, its adapter declares that capability and the resolution ladder uses it before waiting for events.