Zum Hauptinhalt springen

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:

DomainErgebnis
cockpit-os.de (plus MAIL_PLATFORM_DOMAINS)Plattform — kein Center, nicht im Kunden-Reiter
schon mailDomain eines Centershängt automatisch an dieses Center
unbekannt, ohne centerIdeigenständig (Host Europe / Büro ohne Mall)
centerId gesetztwie 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​

GruppeInhalt
Betrieb / ITMAILCOW_API_KEY auf dem Dashboard, IP-Freigabe beim Mail-Anbieter, Migration anwenden
Agenten / MCPTools cockpit_*mailbox*, cockpit_*mail_alias* und cockpit_mailcow_* (OAuth: Super-Admin, Plattform-Admin, Developer; Org-Keys nicht)
Redaktion / BetriebCenter-Detail → Reiter E-Mail (?tab=mail). Postfach, Weiterleitung und neues Passwort: Super-Admin, Plattform-Admin, Center-Admin, Org-Marketing, Content-Editor, Agentur-Redaktion. Lesen zusätzlich Center-Manager. DNS-Setzen: Super-Admin, Plattform-Admin, Center-Admin. Plattform-Postfächer und mailcow-UI: Session/API mit Super-Admin oder Plattform-Admin (Dashboard-Menü „API & Keys“ weiterhin nur Super-Admin).
BesucherFormulare laufen weiter über Resend; Ziel kann eine mailcow-Adresse sein

Wo​

Speichern​

Tabelle / FeldRolle
ShoppingCenter.mail_domainApex-Domain für Kunden-Mail (unabhängig von der Website-Domain)
center_mailboxes / center_mail_aliasesInventar (kein Passwort). centerId optional, ownerKind = center | platform | standalone

AgencyOS​

MethodePfad
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 und Plattform-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.

Erste Domain in mailcow: Hat die Domain im Mail-Inventar noch kein Postfach und keine Weiterleitung, legt das Anlegen die Domain in mailcow als lokal an (nicht nur Weiterleitung). Dann können externe Absender (553) und der Empfang nach MX-Wechsel betroffen sein. GET Center-Mailboxes und erfolgreiches POST liefern optional provisionWarning; nach dem ersten Inventar-Eintrag ist provisionWarning null, POST setzt registeredMailcowDomain: true nur beim ersten Mal. UI: Center-Reiter E-Mail, Dialog „Postfach anlegen“. Nutzer-Doku: E-Mail am Center.

Alias anlegen: localPart, target (Pflicht), optional domain. target kann mehrere Adressen enthalten (komma-, semikolon- oder zeilengetrennt, max. 10) — mailcow leitet an alle weiter.

  • Intern (alle Ziele auf Center-Mail-Domain, vorhandenes Postfach dieses Centers oder Plattform-Adresse wie noreply@cockpit-os.de auf cockpit-os.de): sofort aktiv, keine Extra-Mail. Letzteres ist typisch für Center-Versand (Gutscheine, transaktional): Alias noreply@{Center-Domain} → noreply@cockpit-os.de legt mailcow ohne Bestätigungsmail an. cockpitOS hängt diese Alias-Adresse danach automatisch an die sender_acl des Plattform-SMTP-Postfachs (MAIL_SMTP_USER, Fallback MAIL_FROM_EMAIL / noreply@cockpit-os.de), damit Versand mit Absender noreply@{Center-Domain} nicht mit SMTP 553 abgelehnt wird.
  • Extern (mindestens ein fremdes Ziel wie Gmail): Eintrag zunächst inaktiv. Jede externe Zieladresse erhält eine Bestätigungsmail. Erst nach Klick auf /mail-alias/verify (ohne Login, per POST) wird der Alias beim Mail-Anbieter angelegt. Link 7 Tage gültig. Erneut senden: Session oder AgencyOS …/verify, MCP-Tool für Alias-Bestätigung (2 Minuten Abstand). Mehrere offene Aliase mit gleichem externen Ziel sind möglich (eindeutiger Pending-Token pro Alias).

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

Alias löschen: Bestätigte Weiterleitungen werden zuerst beim Mail-Anbieter entfernt, danach der Datensatz in center_mail_aliases. Noch nicht bestätigte externe Weiterleitungen (active=false, verifiedAt leer) existieren nur in cockpitOS — Löschen erfolgt nur in der Datenbank, ohne mailcow-Aufruf. Ist ein Alias beim Anbieter bereits weg, wird trotzdem gelöscht (z. B. not_found / access_denied wird toleriert). Es werden nur Alias-Zeilen entfernt, keine Center- oder Mailbox-Daten.

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-FeldVerhalten
recipientEmail / customRecipienterlaubt, wenn die Adresse Postfach, Alias, Center-E-Mail oder formRecipients ist
formKeyzuerst 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​

ToolZweck
cockpit_list_mailboxesListe
cockpit_create_mailboxAnlegen, Passwort einmalig
cockpit_update_mailboxQuota, aktiv, Name
cockpit_delete_mailboxLöschen, nur mit confirm=true
cockpit_reset_mailbox_passwordNeues Passwort, nur mit confirm=true, einmal in der Antwort
cockpit_list_mail_aliasesWeiterleitungen
cockpit_create_mail_aliasWeiterleitung (extern: wartet auf Bestätigung)
cockpit_resend_mail_alias_verificationBestätigung erneut senden
cockpit_delete_mail_aliasLöschen, nur mit confirm=true
cockpit_mail_dns_planSoll-Records, UD-Ist und Live-DNS-Abgleich (drift), optional CSV (format=csv)
cockpit_mail_dns_applyBei UD setzen; Standard Dry-Run, Schreiben nur mit confirm=true
cockpit_mailcow_admin_statusWas die API kann (UI-Texte, App-Links); viaApi.fail2ban nur true, wenn Fail2ban live lesbar ist
cockpit_mailcow_list_fail2banAktive Netfilter-Sperren, Allow-/Denylist lesen
cockpit_mailcow_fail2ban_editIP unban oder whitelist — nur confirm=true
cockpit_mailcow_set_uiLogin/Admin-Titel, Hilfe, Footer — nur confirm=true, ganze Instanz
cockpit_mailcow_set_app_linksEigene 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 — cockpitOS-Inventar (Quota-Nutzung wird vom Mail-Anbieter ergänzt, falls konfiguriert).
  9. cockpit_list_mail_aliases — Standard: cockpitOS-Inventar; mit Query includeMailcow=true zusätzlich Anbieter-Aliase (siehe AgencyOS-Antwortfelder in der API-Doku).
  10. 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.
  11. cockpit_mail_dns_plan — Warnings lesen (fremder MX?). Dann cockpit_mail_dns_apply zuerst ohne dryRun=false, danach mit confirm=true.
  12. Dashboard: Center öffnen → Reiter E-Mail. Postfach anlegen oder Neues Passwort. Outlook-Daten stehen im Reiter. DNS-Setzen bleibt Betrieb.
  13. 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​

EnvPflichtBedeutung
MAILCOW_API_KEYjaRead-Write-Key, nur serverseitig
MAILCOW_API_BASE_URLneinStandard https://mail.cockpit-os.de/api/v1
MAIL_DEFAULT_QUOTA_MBneinStandard 2048
MAIL_MAX_MAILBOX_QUOTA_MBneinStandard 10240
MAIL_PUBLIC_HOSTNAMEneinMX/Autodiscover-Ziel, Standard mail.cockpit-os.de
MAIL_PLATFORM_DOMAINSneinZusatz zu cockpit-os.de, kommagetrennt

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

Render/Cloud: Ausgehende mailcow-Requests vom Dashboard nutzen IPv4 zuerst, 25s Timeout und bis zu drei Retries (wie UD Reseller). Persistent fetch failed bei cockpit_mailcow_list_fail2ban: MAILCOW_API_BASE_URL, API-Key und IP-Freigabe in mailcow prüfen — Fehlertext nennt DNS/TLS/Timeout.

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

Notfall: hängende unbestätigte Weiterleitung (nur Betrieb)​

Wenn Anlegen mit 409 existiert bereits scheitert, DELETE aber vor dem Fix mit mailcow-Fehler abbricht: nach Deploy AgencyOS DELETE …/mail-aliases/{aliasId} (Super-Admin- oder Org-Key mit Center-Zugriff) oder im Dashboard Reiter E-Mail → Weiterleitung löschen.

Ohne Deploy (nur Inventar bereinigen, Adresse war nie beim Mail-Anbieter):

# DATABASE_URL = Produktion (Render/Secret), packages/database
cd packages/database
npx prisma db execute --stdin <<'SQL'
DELETE FROM center_mail_aliases
WHERE id = '72604b4f-f7e7-4389-9344-1fbb8e5b7d89'
AND active = false
AND verified_at IS NULL;
SQL

Vorher prüfen: SELECT id, address, active, verified_at FROM center_mail_aliases WHERE address = 'info@thueringereinkaufscenter.de'; — nur die unbestätigte Zeile löschen. Kein Cascade auf Center/Shops.

Catch-up: sender_acl für bestehende noreply-Aliase​

Bereits angelegte noreply@{Center-Domain} → Plattform ohne sender_acl (553 im Versand):

pnpm mail:noreply-sender-acl:backfill
pnpm mail:noreply-sender-acl:backfill -- --apply

Optional --center-id <uuid>. Standard ist Dry-Run (nur fehlende Einträge listen); --apply ruft mailcow idempotent auf. Die Alias-Liste kommt aus mailcow (inkl. manuell angelegter mailcowOnly-Zeilen), vereinigt mit dem cockpit-Inventar. Beispiel Thüringen: fehlt noreply@thueringereinkaufscenter.de in der sender_acl, erscheint die Adresse im Dry-Run unter missing.

409 / mailcowOnly: cockpit_create_mail_alias mit internem noreply → Plattform: Existiert der Alias schon nur in mailcow, wird kein Abbruch ohne ACL mehr erzwungen — sender_acl wird idempotent nachgezogen und der Eintrag ins Inventar übernommen (wie frische Anlage).

Bis zum Deploy: fehlende ACL-Einträge können interim in der mailcow-UI am Plattform-SMTP-Postfach gesetzt werden.

Abgrenzung zu System-Mails​

Transaktionaler Versand (Passwort, Formular, Social, …) läuft über SMTP/mailcow (MAIL_SMTP_*, siehe Dashboard-E-Mails). Legacy: MAIL_TRANSPORT=resend. Diese Schicht legt Empfänger-Postfächer, Weiterleitungen und optional Center-Absender (MAIL_FROM_AUTO_ELIGIBILITY) an.

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /developer-guide/center-mail-provisioning