---
id: EMAIL-WP-0004
type: workplan
title: "Provide transactional invitation mail delivery"
domain: infotech
repo: email-connect
status: active
owner: codex
topic_slug: netkingdom
created: "2026-08-08"
updated: "2026-08-08"
depends_on:
  - NK-WP-0024
state_hub_workstream_id: "a37e5e4d-090a-4a75-88d2-aacd0c0fd235"
---

# EMAIL-WP-0004 - transactional invitation mail delivery

Extend email-connect beyond mailbox evidence scanning with a narrow,
provider-neutral transactional-send service for user-engine invitations and
verification messages. Email evidence remains non-authoritative.

## T01 - Define the send and evidence contract

```task
id: EMAIL-WP-0004-T01
status: done
priority: high
state_hub_task_id: "ef07126a-3c1b-4a8b-9ec1-252c8844ec49"
```

Define an authenticated HTTP send request derived from the user-engine outbox
envelope, approved templates, recipient/address validation, tenant/template
allow-lists, Idempotency-Key, correlation, redaction, and response/error
semantics. Provider acceptance must not be described as inbox delivery,
awareness, identity, or authorization.

Done when the contract supports invitation-created and invitation-resent
events without accepting arbitrary sender, template, or message content.

Done 2026-08-09: authenticated `/v1/send` accepts only the two invitation
event types, validates recipient/event/idempotency fields, and renders a fixed
portal invitation template. Provider acceptance remains explicitly distinct
from delivery or identity evidence.

## T02 - Implement provider-neutral transactional sending

```task
id: EMAIL-WP-0004-T02
status: done
priority: high
state_hub_task_id: "6a6ae927-4393-480f-a83e-93c9dabe18fe"
```

Implement the HTTP receiver, template rendering, idempotency store, suppression
checks, bounded provider calls, and provider adapter. Start with the approved
IONOS SMTP/STARTTLS lane while keeping provider credentials outside requests,
logs, Git, and database evidence.

Done when repeated event IDs send at most one message and failures return
stable retryable/permanent classifications without leaking SMTP details.

Done 2026-08-09: SQLite idempotency, provider-neutral injection, bounded
STARTTLS SMTP calls, duplicate suppression, and redacted provider-unavailable
responses are implemented. The same narrow service now issues public-
registration mailbox challenges: plaintext handles exist only in the message,
SQLite retains a SHA-256 digest, evidence is purpose/binding scoped, expiry is
enforced, and consumption is atomic and single-use. All 23 repository tests
pass.

## T03 - Establish custody and deploy the service

```task
id: EMAIL-WP-0004-T03
status: progress
priority: high
state_hub_task_id: "13428364-29b1-4e0d-aaf5-c0b254c829b9"
```

Route SMTP and caller credentials through the credential catalog before
requesting them, store provider material in OpenBao, and deliver only scoped
runtime secrets. Deploy an immutable image on railiance01 with probes,
resource/security controls, default-deny NetworkPolicy, restricted
user-engine ingress, SMTP-only egress, and rollback.

Done when user-engine can call the cluster-local receiver without possessing
SMTP credentials and unrelated workloads cannot send through it.

## T04 - Prove invitation delivery failure behavior

```task
id: EMAIL-WP-0004-T04
status: todo
priority: high
state_hub_task_id: "34127b3e-f7c6-4ebe-a86c-743ba1b27640"
```

Test template allow-list denial, invalid recipient, provider timeout, temporary
deferral, permanent rejection, duplicate request, suppression, resend, and
redacted diagnostics. Verify mailbox ownership and provider acceptance never
alter user-engine authorization. Hand non-secret message/event references and
failure evidence back to NK-WP-0024.

Done when deployed invitation and verification flows are observable,
idempotent, retry-safe, and conservative about delivery evidence.