Company Email infrastructure and service notifications #5030

🤖 Generated by the Agentic Engineer

Design: ADR 0009, Phase 2 (devantler-tech/monorepo#4280, spike devantler-tech/monorepo#4275).

Problem

The maintainer wants self-hosted company email, including migration of an existing custom-domain mailbox from iCloud and access from normal mail apps. Private agent correspondence must never reach a public artifact. The sites could also use this platform capability for transactional mail. Spend stewardship remains disabled until its separate contract is resolved.

Proposed direction

Run a mail service on the platform as a platform capability:

• Server: a maintained, self-hostable mail server with SMTP, IMAP or JMAP and built-in DKIM, for example Stalwart. Pin it to an exact release, and check its maintenance and license first.
• Domain and migration: move the existing custom-domain mailbox from iCloud, following the maintainer's direct direction on 2026-10-24. Other addresses on that domain may be retired gracefully. Inventory them privately, preserve existing messages, verify the destination and rollback before the domain-wide MX cutover, and never delete shared iCloud history as a side effect. DNS changes go through the owning repository. Exact mailbox addresses and account details stay in private operator configuration.
• Inbound: accept mail only for the service's own addresses, and never act as an open relay. A reply from the maintainer counts only when DMARC passes for one of his own addresses.
• Outbound: direct delivery from the maintainer's server, selected explicitly on 2026-10-25. Verify outgoing port 25 is allowed, a stable public sending identity and matching reverse DNS before activation. If the provider restriction remains, prepare the exact unblock request for the maintainer to submit. Verify real inbox delivery with SPF, DKIM and DMARC passing.
• Sending limits: the agents' service account may send only to the maintainer's own addresses, enforced by the server.
• Business site email: provide a dedicated automated sender with its own credential and enforced sender identity for messages to the maintainer or clients. Sending stays server-side and delivery failures are observable. Recipient restrictions on the agents' separate account remain enforced. Password resets and announcements are application use cases; do not activate undeployed application features as a side effect.
• Credentials: generated in the cluster (for example with an ExternalSecrets password generator), stored in OpenBao, and delivered to workloads by ExternalSecrets. The agents' host gets its copy once, through a step the maintainer performs, and scripts read it from the macOS Keychain at run time. No credential is ever written to a repository, an issue or a log.
• Storage and backup: mail data is backed up like the other stateful apps. Preserve company mailbox history; bounded retention applies only to a separate agent/digest mailbox, never globally to company mail.

Acceptance criteria

• The existing mailbox is migrated with its history preserved, other domain addresses are retired gracefully, and rollback is recorded privately.

• The maintainer can add the mailbox to normal mail apps using verified IMAP/TLS and authenticated SMTP submission.

• Homepage presents Stalwart with its logo in an Email section at https://platform.devantler.tech. The visible entry, administration link and successful browser navigation were verified after fix(homepage): show Stalwart with its logo under Email #5482.

• A test message from the service reaches the maintainer's inbox, not spam, with SPF, DKIM and DMARC passing.

• His reply is accepted, and a forged reply (DMARC fail) is rejected or marked untrusted.

• An open-relay test fails, and the agents' account cannot send to any other address.

• The business site's dedicated sender can deliver an authorized test with SPF, DKIM and DMARC passing; another sender identity is refused, credentials stay server-side, and failure reporting works.

• No credential appears in git, in an issue or in a log, and the agents' scripts fetch theirs from the Keychain.

• Mail data is in the backup set, and a restore is tested once.

• OIDC sign-in works through the existing identity provider for the maintainer's own Email administrator account. Retain a separate administrator only where normal access and a tested recovery path demonstrate its necessity.

• Company Email uses transparent encryption of persistent server storage, with operational keys in approved service custody and independent bootstrap recovery. Ordinary mail apps can read messages without per-client S/MIME identities. Verify safe migration, new delivery and actual backup restoration, and document what is protected and what remains visible.

• Email credentials use the canonical infrastructure custody and Email naming. Verify migration and readback before retiring any legacy custody; preserve recovery material and history.

• Recreating the service from reviewed declarative configuration and approved private custody restores its accounts, sign-in, sender and recipient limits, and encryption settings. A restore exercise proves data and configuration recovery.

Size

L. Preparation delivered by #5288 / #5289. Remaining slices: safe mailbox configuration and restrictions; migration, DNS and outbound delivery; client setup and the real inbox/reply/backup-restore proofs.