GovOPlaN Mail is the mail transport module. It owns reusable SMTP/IMAP profile management, mail profile policy enforcement, mock mail infrastructure, and the mail WebUI package.

Ownership

This repository owns:

backend module manifest mail
mail permissions such as mail:profile:read, mail:profile:write_own, mail:profile:write, mail:profile:use, mail:profile:test, and mail:mailbox:read
SMTP/IMAP profile models, policy checks, encrypted credential storage, and profile resolution
SMTP send and IMAP append adapters, including mock transports for development
development mock mailbox endpoints used by test-send flows
WebUI package @govoplan/mail-webui with profile management, policy management, and read-only mailbox components

Core owns auth, tenants, RBAC evaluation, database/session primitives, secret helpers, CSRF/API helpers, and shell layout.

Profile and credential ownership

Mail profiles are separate governed definitions. Mail owns their SMTP/IMAP endpoints, encrypted credentials, tests, scope, and policy. Consumers such as Campaign store only a stable profile identifier and resolve the authorized, active profile through mail.campaign_delivery; they never copy or override transport settings or credentials in their own JSON.

The campaign capability returns read-only availability flags and random, persisted Mail-owned transport revisions without decrypting secrets. Effect calls perform authorization, revision comparison, credential resolution, policy checks, and SMTP/IMAP effects inside Mail. Consumer-visible outcomes are sanitized: provider banners, raw response bytes, hosts, account identities, and credentials are not returned.

A remaining observability slice, tracked in govoplan-mail#17, is a Mail-owned durable outbox and transport-attempt store with restricted diagnostic access, retention controls, and correlation identifiers. Until that exists, Campaign retains only sanitized delivery evidence; raw provider diagnostics must not be copied into consumer records.

SMTP effects decrypt only SMTP credentials; Sent-folder effects decrypt only IMAP credentials. A connection loss after an effect starts is surfaced as an unknown outcome. Campaign does not automatically retry an unknown IMAP append, preventing silent duplicate Sent copies while an operator inspects the mailbox.

The existing SMTP/IMAP credential-inheritance policy remains part of the Mail policy model for compatibility. Campaign delivery requires effective inheritance: a policy that requires campaign-local credentials now fails closed with guidance to store those credentials on a Mail profile and enable inheritance.

Deleting a profile deactivates its non-secret tombstone metadata and scrubs both encrypted SMTP and IMAP passwords immediately in the same transaction as a non-secret audit event. Destructive module retirement applies the same rule to every remaining profile before any Mail table is dropped; a scrub or audit failure blocks retirement.

Personal profile self-service is a distinct authorization path. An actor with mail:profile:write_own can mutate only a user-scoped profile whose scope id is their current tenant membership id; mail:secret:manage_own applies the same ownership check to credentials. Neither scope permits profile-policy changes or management of tenant, group, campaign, system, or another user's profiles. Changing an SMTP/IMAP endpoint while a stored password remains is a secret operation and requires the matching credential permission. Deactivating a credential-free profile needs only profile-write authority; if a password will be scrubbed, credential authority is required and the deletion is audited.

Development

Install through the core environment:

cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m pip install -r requirements-dev.txt

Run the WebUI from the core host:

cd /mnt/DATA/git/govoplan-core/webui
PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run dev

Module integration

Backend entry point:

[project.entry-points."govoplan.modules"]
mail = "govoplan_mail.backend.manifest:get_manifest"

Frontend package:

@govoplan/mail-webui

The campaign module consumes mail.campaign_delivery for authorized runtime profile resolution, sending, append-to-Sent behavior, profile selection, and policy checks. Mail does not import campaign internals; campaign-scoped policy and owner context are resolved through the core campaigns.mailPolicyContext capability when the campaign module is installed.

Development mailbox routes are registered by the mail module only when the core runtime is in dev mode and dev_mailbox_api_enabled is enabled. Core does not contribute these routes directly.

POP3 and JMAP are deferred. The protocol decision is documented in docs/MAIL_PROTOCOL_ROADMAP.md: stabilize SMTP/IMAP first, prefer JMAP for modern mailbox sync/search later, and add POP3 only for explicit legacy-download requirements.

Platform RBAC and governance rules are documented in govoplan-core/docs/. The Mail handbook provides the adaptive user, governance, technical, security, and operations perspectives.

Release packaging

The repository root includes a package.json for git-based WebUI installs. It exports the package @govoplan/mail-webui from webui/src so release builds can depend on tagged git refs instead of local file: paths.