---
id: WF-PFM-NOT-015
title: Provision, verify and remove the association sender
trigger: Workspace lifecycle setup, an HQ sender read, sending or deletion needs sender identity handling.
product_area: platform
module: notifications
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
- CAP-PFM-NOT-020
moves:
- STATE-PFM-NOT-014
crosses:
- SVC-PFM-NOT-communications
hops:
- n: 1
  actor_or_service: Workspace lifecycle participant (provision)
  action: Create or adopt the chosen SES identities and store identifiers and DNS instructions while preserving
    the existing verification state; skip absent sender requests.
  anchor: services-platform:modules/communications/services/sender-identity/provision-sender-identity.ts:provisionSenderIdentity
  seam: state_machine
  on_failure: Fail the provisioning step for lifecycle retry.
  left_inconsistent: Retry can adopt a provider identity created before storage failed.
  observer: Provisioning step history.
  provenance: observed
  source: services-platform:modules/communications/services/sender-identity/provision-sender-identity.ts:provisionSenderIdentity
- n: 2
  actor_or_service: Workspace lifecycle participant (verify)
  action: Check that required provider identities exist without waiting for DNS verification.
  anchor: services-platform:modules/communications/services/sender-identity/provision-sender-identity.ts:verifySenderIdentityProvisioned
  seam: state_machine
  on_failure: Fail the lifecycle verification step.
  left_inconsistent: Sender readiness may remain pending while shared sending is available.
  observer: Provisioning job results.
  provenance: observed
  source: services-platform:modules/communications/services/sender-identity/provision-sender-identity.ts:verifySenderIdentityProvisioned
- n: 3
  actor_or_service: Rhythm HQ (workspace lifecycle route)
  action: Refresh provider verification during an HQ sender read, storing the check and retaining the
    first verified time.
  anchor: services-platform:modules/communications/services/sender-identity/provision-sender-identity.ts:refreshSenderIdentityVerification
  seam: sync
  on_failure: Return the sender-read failure.
  left_inconsistent: Stored verification remains at its prior observation.
  observer: HQ sender-read response.
  provenance: observed
  source: services-platform:modules/tenants/aws/api/tenants.routes.ts:getHqTenantEmailSender
- n: 4
  actor_or_service: Send consumer
  action: Select the verified custom sender with a one-minute cache, otherwise use shared sending; Platform
    invitations retain the Platform sender.
  anchor: services-platform:modules/communications/services/sender-identity/tenant-sender-address.ts
  seam: sync
  on_failure: Use the shared fallback where configured sender selection is unavailable.
  left_inconsistent: Sender choice can lag a verification change by the cache interval.
  observer: Message from-address history.
  provenance: observed
  source: services-platform:modules/communications/services/sender-identity/tenant-sender-address.ts
- n: 5
  actor_or_service: Workspace lifecycle participant (purge)
  action: Remove created and adopted provider identities, verify absence, then purge the stored setting.
  anchor: services-platform:modules/communications/services/sender-identity/provision-sender-identity.ts:purgeSenderIdentityIdentities
  seam: state_machine
  on_failure: Report deletion failure to the lifecycle job.
  left_inconsistent: An identity shared by adoption can be removed for another workspace.
  observer: Deletion steps and orphan reporting.
  provenance: observed
  source: services-platform:modules/communications/services/sender-identity/provision-sender-identity.ts:purgeSenderIdentityIdentities
idempotency: Stable provider identity names allow retries to adopt existing identities; the resource registry
  retains created or adopted classification.
concurrency: Each workspace has one setting, while the same provider domain can be adopted across workspaces.
branches:
- Address-only setup needs no domain; combined setup provisions both identities.
waits:
- Customer DNS verification may remain pending indefinitely.
evidence:
- 'services-platform at ad3f6a65: modules/communications/services/sender-identity/*.ts; modules/tenants/aws/api/tenants.routes.ts;
  docs/communications/architecture.md §11.2; docs/hq/rhythm-hq-plan.md §D5 (cited by the participant).'
controls: [TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-PRV-004, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---
# Provision, verify and remove the association sender

## What It Does

Workspace lifecycle setup, an HQ sender read, sending or deletion needs sender identity handling.

## The Flow

```mermaid
flowchart TD
    h0["Create or adopt the chosen SES identities and store identifiers and DNS instructions while preserving the existing "]
    h1["Check that required provider identities exist without waiting for DNS verification"]
    h0 --> h1
    h2["Refresh provider verification during an HQ sender read, storing the check and retaining the first verified time"]
    h1 --> h2
    h3["Select the verified custom sender with a one-minute cache, otherwise use shared sending"]
    h2 --> h3
    h4["Remove created and adopted provider identities, verify absence, then purge the stored setting"]
    h3 --> h4
```

## When Something Fails

The hop rows identify each retry boundary, any state left behind and the available observer. Stable provider identity names allow retries to adopt existing identities; the resource registry retains created or adopted classification. Each workspace has one setting, while the same provider domain can be adopted across workspaces.

## Open Design Questions

Address-only setup needs no domain; combined setup provisions both identities. Customer DNS verification may remain pending indefinitely.