---
id: STATE-PFM-NOT-012
title: Communication message delivery as the provider reports it
object: DOM-PFM-NOT-005
product_area: platform
module: notifications
revision: 1
status: draft
design_intent: confirmed
origin: Andrew 2026-10-09 (open and click tracking on for transactional mail; feedback, suppression and
  history accepted), services-platform:docs/communications/architecture.md#2026-10-09 — Final acceptance
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
- name: unknown
  meaning: Provider delivery outcome has not been reported.
- name: deferred
  meaning: The receiving server postponed delivery.
- name: bounced transient
  meaning: The provider reported a temporary bounce.
- name: delivered
  meaning: The receiving server accepted the message; this does not establish a human read.
- name: rejected
  meaning: The provider rejected the message.
- name: bounced permanent
  meaning: The provider reported a permanent bounce; suppression is attempted separately.
- name: complained
  meaning: The provider reported a spam complaint; suppression is attempted separately.
transitions:
- from: unknown
  to: delivered
  trigger: Primary-recipient feedback reports delivery.
  guard: Delivery must outrank the retained state.
  side_effects:
  - Retain the earliest reported occurrence time.
  who: Feedback processor
  provenance: observed
  source: services-platform:modules/communications/services/feedback/process-ses-event.ts:processSesEvent
- from: unknown
  to: deferred
  trigger: Feedback reports delivery delay.
  guard: Delay must outrank the retained state.
  side_effects: []
  who: Feedback processor
  provenance: observed
  source: services-platform:modules/communications/db/communication-messages.table.ts:DELIVERY_STATE_PRECEDENCE
- from: delivered
  to: bounced permanent
  trigger: Feedback reports a permanent bounce after delivery.
  guard: Permanent bounce outranks delivered.
  side_effects:
  - Attempt address suppression after event commit; a failed attempt can leave future mail unprotected.
  who: Feedback processor
  provenance: observed
  source: services-platform:modules/communications/services/feedback/process-ses-event.ts:processSesEvent
- from: delivered
  to: complained
  trigger: Feedback reports a complaint after delivery.
  guard: Complaint has the highest outcome rank.
  side_effects:
  - Attempt address suppression after event commit; a failed attempt can leave future mail unprotected.
  who: Feedback processor
  provenance: observed
  source: services-platform:modules/communications/services/feedback/process-ses-event.ts:processSesEvent
- from: deferred
  to: delivered
  trigger: Delayed delivery later succeeds.
  guard: Delivery outranks delay.
  side_effects: []
  who: Feedback processor
  provenance: observed
  source: services-platform:modules/communications/db/communication-messages.table.ts:DELIVERY_STATE_PRECEDENCE
invalid:
- from: delivered
  to: deferred
  why: Lower-ranked feedback cannot reverse the retained outcome.
- from: complained
  to: delivered
  why: No delivery report can replace a complaint.
concurrency: Derived provider-event identities ignore repeats. Outcome precedence and minimum timestamps
  tolerate reordered events. Copy-recipient reports remain in history but do not change the primary recipient's
  delivery state.
evidence:
- 'services-platform at ad3f6a65: modules/communications/services/feedback/process-ses-event.ts; db/communication-messages.table.ts;
  docs/communications/architecture.md §8.3 to §8.5, §16.5.'
---
# Communication message delivery as the provider reports it

## The Lifecycle

```mermaid
stateDiagram-v2
    state "unknown" as s0
    state "deferred" as s1
    state "bounced transient" as s2
    state "delivered" as s3
    state "rejected" as s4
    state "bounced permanent" as s5
    state "complained" as s6
    s0 --> s3
    s0 --> s1
    s3 --> s5
    s3 --> s6
    s1 --> s3
```

## Transitions Explained

The transition rows describe stored state changes, their checks and their recorded effects. A queue receive, provider outcome and staff action can reach different lifecycle boundaries.

## What Cannot Happen

Lower-ranked feedback cannot reverse the retained outcome. No delivery report can replace a complaint.

## Concurrency and Timing

Derived provider-event identities ignore repeats. Outcome precedence and minimum timestamps tolerate reordered events. Copy-recipient reports remain in history but do not change the primary recipient's delivery state.