feat: bridge observed messages to postboxes

src/govoplan_mail/backend/manifest.py

@@ -10,7 +10,9 @@ from govoplan_core.core.mail import (
     CAPABILITY_MAIL_BOUNCE_PROCESSING,
     CAPABILITY_MAIL_DELIVERY_OUTBOX,
     CAPABILITY_MAIL_NOTIFICATION_DELIVERY,
+    CAPABILITY_MAIL_POSTBOX_BRIDGE,
 )
+from govoplan_core.core.postbox import CAPABILITY_POSTBOX_DELIVERY
 from govoplan_core.core.module_guards import drop_table_retirement_provider, persistent_table_uninstall_guard
 from govoplan_core.core.modules import (
     DocumentationCondition,
@@ -311,13 +313,14 @@ manifest = ModuleManifest(
     name="Mail",
     version="0.1.18",
     required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
-    optional_dependencies=("campaigns", "addresses", "calendar", "search"),
+    optional_dependencies=("campaigns", "addresses", "calendar", "postbox", "search"),
     provides_interfaces=(
         ModuleInterfaceProvider(name="mail.campaign_delivery", version="0.2.0"),
         ModuleInterfaceProvider(name="mail.delivery_commands", version="0.1.0"),
         ModuleInterfaceProvider(name="mail.delivery_outbox", version="0.1.0"),
         ModuleInterfaceProvider(name="mail.notification_delivery", version="0.1.0"),
         ModuleInterfaceProvider(name="mail.bounce_processing", version="0.1.0"),
+        ModuleInterfaceProvider(name=CAPABILITY_MAIL_POSTBOX_BRIDGE, version="1.0.0"),
     ),
     requires_interfaces=(
         ModuleInterfaceRequirement(
@@ -344,6 +347,12 @@ manifest = ModuleManifest(
             version_max_exclusive="0.2.0",
             optional=True,
         ),
+        ModuleInterfaceRequirement(
+            name=CAPABILITY_POSTBOX_DELIVERY,
+            version_min="0.1.0",
+            version_max_exclusive="0.2.0",
+            optional=True,
+        ),
         ModuleInterfaceRequirement(
             name="search.source",
             version_min="1.0.0",
@@ -454,8 +463,39 @@ manifest = ModuleManifest(
             "govoplan_mail.backend.bounce_processing",
             fromlist=["SqlMailBounceProcessingProvider"],
         ).SqlMailBounceProcessingProvider(),
+        CAPABILITY_MAIL_POSTBOX_BRIDGE: lambda context: __import__(
+            "govoplan_mail.backend.postbox_bridge",
+            fromlist=["create_postbox_bridge"],
+        ).create_postbox_bridge(context),
     },
     documentation=(
+        DocumentationTopic(
+            id="mail.postbox.bridge",
+            title="Bridge selected Mail observations into Postbox",
+            summary="Deliver one immutable IMAP observation to an explicit function Postbox without turning Postbox into a mailbox account.",
+            body=(
+                "Mail exposes an optional, idempotent bridge capability. A configured caller supplies an exact Mail profile, folder, UIDVALIDITY, UID, raw observation, "
+                "and typed Postbox target. Mail parses bounded headers, plaintext, participants, and attachment evidence; Postbox owns target resolution, "
+                "delivery, retention, receipts, and access. The bridge stores no credentials in Postbox and never treats account login as Postbox membership."
+            ),
+            layer="configured",
+            documentation_types=("admin", "user"),
+            audience=("mail_user", "mail_admin", "administrator"),
+            related_modules=("postbox", "idm", "organizations"),
+            translations={
+                "de": {
+                    "title": "Ausgewählte Mail-Beobachtungen an Postbox übergeben",
+                    "summary": "Eine unveränderliche IMAP-Beobachtung an ein ausdrücklich bestimmtes Funktionspostfach liefern, ohne Postbox zu einem Mailkonto zu machen.",
+                    "body": (
+                        "Mail stellt eine optionale, idempotente Bridge-Capability bereit. Ein konfigurierter Aufrufer übergibt ein exaktes Mailprofil, Ordner, UIDVALIDITY, UID, die rohe Beobachtung "
+                        "und ein typisiertes Postbox-Ziel. Mail liest begrenzte Kopfzeilen, Klartext, Beteiligte und Anlagennachweise; Postbox besitzt Zielauflösung, Zustellung, "
+                        "Aufbewahrung, Belege und Zugriff. Die Bridge speichert keine Zugangsdaten in Postbox und behandelt die Kontoanmeldung niemals als Postfachmitgliedschaft."
+                    ),
+                }
+            },
+            metadata={"kind": "guide", "help_contexts": ["mail.postbox-bridge"]},
+            order=36,
+        ),
         DocumentationTopic(
             id="mail.configuration-package.smtp-profile",
             title="Provision SMTP profiles from deployment receipts",