Center-Mail (Mailbox & Alias)

Was

cockpitOS kann Postfächer und Weiterleitungen anlegen, listen, ändern und löschen. Das Inventar liegt in cockpitOS. Der aktuelle Anbieter (Servercow / mailcow unter mail.cockpit-os.de) steckt hinter einem MailProvider — MCP, v0 und AgencyOS-Clients kennen den Anbieter nicht.

Ein Center ist nicht Pflicht. Die Domain entscheidet den Owner:

Domain	Ergebnis
cockpit-os.de (plus MAIL_PLATFORM_DOMAINS)	Plattform — kein Center, nicht im Kunden-Reiter
schon mailDomain eines Centers	hängt automatisch an dieses Center
unbekannt, ohne centerId	eigenständig (Host Europe / Büro ohne Mall)
centerId gesetzt	wie bisher am Center; Plattform-Domains sind dort verboten

Phase 0: API + MCP. Phase 0b: Formulare (Resend) dürfen an angelegte Center-Postfächer und Aliase senden. Phase 1: DNS-Plan (MX/SPF/DKIM) anzeigen und nach Bestätigung bei United Domains setzen. Phase 2: Reiter E-Mail am Center. Externe Weiterleitungen erst nach Bestätigung der Zieladresse. Keine Host-Europe-Migration, kein automatisches Anlegen beim Onboarding.

Warum

Kunden brauchen Adressen wie info@kunde.de oder gewinnspiel@kunde.de. Formulare auf v0-Websites senden weiter per Resend an eine Allowlist-Adresse (formRecipients). Dafür muss die Zieladresse existieren — als Mailbox oder als Alias.

Wer ist betroffen

Gruppe	Inhalt
Betrieb / IT	MAILCOW_API_KEY auf dem Dashboard, IP-Freigabe beim Mail-Anbieter, Migration anwenden
Agenten / MCP	Tools cockpit_*mailbox*, cockpit_*mail_alias* und (nur Super-Admin) cockpit_mailcow_*
Redaktion / Betrieb	Center-Detail → Reiter E-Mail (?tab=mail). Postfach, Weiterleitung und neues Passwort: Super-Admin, Center-Admin, Org-Marketing, Content-Editor, Agentur-Redaktion. Lesen zusätzlich Center-Manager. DNS-Setzen nur Super-Admin / Center-Admin. Plattform-Postfächer: Einstellungen → API (nur Super-Admin).
Besucher	Formulare laufen weiter über Resend; Ziel kann eine mailcow-Adresse sein

Wo

Speichern

Tabelle / Feld	Rolle
ShoppingCenter.mail_domain	Apex-Domain für Kunden-Mail (unabhängig von der Website-Domain)
center_mailboxes / center_mail_aliases	Inventar (kein Passwort). centerId optional, ownerKind = center | platform | standalone

AgencyOS

Methode	Pfad
GET POST	/api/agencyos/v1/centers/{centerId}/mailboxes
PATCH DELETE	/api/agencyos/v1/centers/{centerId}/mailboxes/{mailboxId}
GET POST	/api/agencyos/v1/centers/{centerId}/mail-aliases
POST	/api/agencyos/v1/centers/{centerId}/mail-aliases/{aliasId}/verify
DELETE	/api/agencyos/v1/centers/{centerId}/mail-aliases/{aliasId}
GET POST	/api/agencyos/v1/centers/{centerId}/mail-dns
GET POST	/api/agencyos/v1/mailboxes
PATCH DELETE	/api/agencyos/v1/mailboxes/{mailboxId}
POST	/api/agencyos/v1/mailboxes/{mailboxId}/password
GET POST	/api/agencyos/v1/mail-aliases
DELETE	/api/agencyos/v1/mail-aliases/{aliasId}
POST	/api/agencyos/v1/mail-aliases/{aliasId}/verify
GET POST	/api/agencyos/v1/mailcow/ui

Center-Pfade bleiben. Ohne centerId (unified): nur globaler oder persönlicher Super-Admin-Key. Antwort enthält ownerKind und ggf. attachedBy (explicit, mailDomain, customDomain, platform, unclaimed).

Dieselben Center-Operationen gibt es mit Dashboard-Session unter /api/centers/{centerId}/mailboxes, mail-aliases und mail-dns (kein AgencyOS-Bearer). Super-Admin zusätzlich: GET/POST /api/mailboxes und /api/mailcow/ui.

Mailbox anlegen: localPart (Pflicht), optional centerId, domain, quotaMb (Standard 2048), name. Ohne Center ist domain Pflicht.
Antwort enthält password nur einmal. Nicht loggen.

Alias anlegen: localPart, target (Pflicht), optional domain.

• Intern (Ziel-Domain = Center-Mail-Domain, oder vorhandenes Postfach dieses Centers): sofort aktiv, keine Extra-Mail.
• Extern (Gmail, Host Europe, privat): Eintrag zunächst inaktiv. Resend schickt eine Bestätigung an das Ziel. Erst nach Klick auf /mail-alias/verify (ohne Login, per POST) legt cockpitOS den Alias beim Mail-Anbieter an. Link 7 Tage gültig. Erneut senden: Session oder AgencyOS …/verify, MCP cockpit_resend_mail_alias_verification (2 Minuten Abstand).

Antwort enthält verificationRequired und verificationEmailSent. Formulare sehen nur aktive Aliase.

Domain-Reihenfolge: übergebene domain → mailDomain am Center → Apex von customDomain. Eine zweite Mail-Domain pro Center ist in Phase 0 nicht vorgesehen.

Formulare (Phase 0b)

Versand bleibt Resend (POST …/send-contact-inquiry). Aktive Einträge in center_mailboxes und center_mail_aliases stehen automatisch auf der Empfänger-Allowlist.

v0-Feld	Verhalten
recipientEmail / customRecipient	erlaubt, wenn die Adresse Postfach, Alias, Center-E-Mail oder formRecipients ist
formKey	zuerst templateContent.formRecipients.{formKey}; sonst Postfach/Alias mit gleichem localPart (nicht bei Standardkeys wie kontakt)

Website-Config wird beim Anlegen einer Mailbox nicht beschrieben. Löschen der Mailbox nimmt die Adresse wieder aus der Allowlist.

MCP

Tool	Zweck
cockpit_list_mailboxes	Liste
cockpit_create_mailbox	Anlegen, Passwort einmalig
cockpit_update_mailbox	Quota, aktiv, Name
cockpit_delete_mailbox	Löschen, nur mit confirm=true
cockpit_reset_mailbox_password	Neues Passwort, nur mit confirm=true, einmal in der Antwort
cockpit_list_mail_aliases	Weiterleitungen
cockpit_create_mail_alias	Weiterleitung (extern: wartet auf Bestätigung)
cockpit_resend_mail_alias_verification	Bestätigung erneut senden
cockpit_delete_mail_alias	Löschen, nur mit confirm=true
cockpit_mail_dns_plan	Soll-Records anzeigen, nichts schreiben
cockpit_mail_dns_apply	Bei UD setzen; Standard Dry-Run, Schreiben nur mit confirm=true
cockpit_mailcow_admin_status	Was die API kann (UI-Texte, App-Links; nicht Logo/SOGo)
cockpit_mailcow_set_ui	Login/Admin-Titel, Hilfe, Footer — nur confirm=true, ganze Instanz
cockpit_mailcow_set_app_links	Eigene App-Links — nur confirm=true. Zeilen aus vars.local.inc.php bleiben

mailcow-Instanz (Admin, nicht Center)

Das ist nicht Postfach-Alltag. Super-Admin kann über MCP die mailcow-Login-/Admin-Oberfläche setzen (Titel, Hilfetext, Footer, eigene App-Links). Gleicher MAILCOW_API_KEY wie für Postfächer — kein zweiter Key.

Nicht über die API: Logo-Upload, SOGo-Look, gesperrte Zeilen in vars.local.inc.php (Servercow). UI-Texte sind in mailcow ein Vollsatz — nicht mitgegebene Felder (Hilfe, Footer) können leer werden. Zuerst cockpit_mailcow_admin_status, dann cockpit_mailcow_set_ui mit allen Texten, die bleiben sollen.

Org-AgencyOS-Keys dürfen das nicht. Dashboard-Session: nur Rolle Super-Admin.

So testen

1. Migrationen anwenden: 20260903160000_add_center_mail_SAFE.sql, 20260909090000_add_mail_alias_verify_SAFE.sql und 20260909100000_add_mail_owner_kind_SAFE.sql
2. Auf dem Dashboard-Service MAILCOW_API_KEY und optional MAILCOW_API_BASE_URL=https://mail.cockpit-os.de/api/v1 setzen. Die öffentliche IP des Dashboards in der mailcow-API-Freigabe eintragen.
3. Testdomain wählen, die noch nicht produktiv MX auf Host Europe braucht.
4. cockpit_create_mailbox mit centerId, localPart=test, domain=… — oder ohne Center localPart=dmarc, domain=cockpit-os.de
5. Webmail unter https://mail.cockpit-os.de mit der einmaligen Response-Adresse und dem Passwort prüfen.
6. cockpit_create_mail_alias z. B. localPart=gewinnspiel, target= bestehende Adresse auf der Center-Domain — sofort aktiv.
7. Externes Ziel (z. B. Gmail): Antwort verificationRequired=true. Bestätigungsmail öffnen, Button klicken. Reiter zeigt Bestätigung offen bis dahin. cockpit_resend_mail_alias_verification bei Bedarf.
8. cockpit_list_mailboxes / cockpit_list_mail_aliases — Einträge kommen aus cockpitOS.
9. Formular: POST …/send-contact-inquiry mit recipientEmail=info@… oder formKey = localPart — Resend stellt zu, mailcow empfängt. Unbestätigte Aliase stehen nicht auf der Allowlist.
10. cockpit_mail_dns_plan — Warnings lesen (fremder MX?). Dann cockpit_mail_dns_apply zuerst ohne dryRun=false, danach mit confirm=true.
11. Dashboard: Center öffnen → Reiter E-Mail. Postfach anlegen oder Neues Passwort. Outlook-Daten stehen im Reiter. DNS-Setzen bleibt Betrieb.
12. Admin: cockpit_mailcow_admin_status — viaApi.uiTexts und appLinks true, logo/sogoBranding false. UI-Texte nur setzen, wenn die gewünschten Werte feststehen und confirm=true.

DNS (Phase 1)

Soll-Records: MX auf mail.cockpit-os.de, SPF (nur wenn noch keiner da), DKIM aus mailcow, DMARC p=none (nur wenn fehlt), Autodiscover/Autoconfig, SRV. Kein A-Record mail auf der Kundenzone.

Schreiben nur bei United Domains. Vorhandenes SPF/DMARC wird nicht überschrieben. MX-Wechsel bedeutet: Empfang geht zu mailcow, das alte Postfach (z. B. Host Europe) bekommt nichts mehr. Status ok gilt, wenn Host (auch als volle Domain) und Wert bereits passen — nicht erst nach einem erneuten Schreiben.

Betrieb

Env	Pflicht	Bedeutung
MAILCOW_API_KEY	ja	Read-Write-Key, nur serverseitig
MAILCOW_API_BASE_URL	nein	Standard https://mail.cockpit-os.de/api/v1
MAIL_DEFAULT_QUOTA_MB	nein	Standard 2048
MAIL_MAX_MAILBOX_QUOTA_MB	nein	Standard 10240
MAIL_PUBLIC_HOSTNAME	nein	MX/Autodiscover-Ziel, Standard mail.cockpit-os.de
MAIL_PLATFORM_DOMAINS	nein	Zusatz zu cockpit-os.de, kommagetrennt

Kein Key im Repo, in MCP-Tool-Definitionen oder Client-Code. Passwörter nicht in Logs.

Nicht in Phase 0–2: Automatisches MX ohne Bestätigung, Host-Europe-Umzug, automatisches Anlegen beim Center-Onboarding.

Abgrenzung zu System-Mails

Dashboard- und Formularversand laufen weiter über Resend. Diese Schicht legt nur Empfänger-Postfächer bzw. Weiterleitungen an. Siehe Dashboard-E-Mails.