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 cockpit_mailcow_* (OAuth: Super-Admin, Plattform-Admin, Developer; Org-Keys nicht) |
| Redaktion / Betrieb | Center-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). |
| 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 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.deaufcockpit-os.de): sofort aktiv, keine Extra-Mail. Letzteres ist typisch für Center-Versand (Gutscheine, transaktional): Aliasnoreply@{Center-Domain}→noreply@cockpit-os.delegt mailcow ohne Bestätigungsmail an. cockpitOS hängt diese Alias-Adresse danach automatisch an die sender_acl des Plattform-SMTP-Postfachs (MAIL_SMTP_USER, FallbackMAIL_FROM_EMAIL/noreply@cockpit-os.de), damit Versand mit Absendernoreply@{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-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, UD-Ist und Live-DNS-Abgleich (drift), optional CSV (format=csv) |
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); viaApi.fail2ban nur true, wenn Fail2ban live lesbar ist |
cockpit_mailcow_list_fail2ban | Aktive Netfilter-Sperren, Allow-/Denylist lesen |
cockpit_mailcow_fail2ban_edit | IP unban oder whitelist — nur confirm=true |
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
- Migrationen anwenden:
20260903160000_add_center_mail_SAFE.sql,20260909090000_add_mail_alias_verify_SAFE.sqlund20260909100000_add_mail_owner_kind_SAFE.sql - Auf dem Dashboard-Service
MAILCOW_API_KEYund optionalMAILCOW_API_BASE_URL=https://mail.cockpit-os.de/api/v1setzen. Die öffentliche IP des Dashboards in der mailcow-API-Freigabe eintragen. - Testdomain wählen, die noch nicht produktiv MX auf Host Europe braucht.
cockpit_create_mailboxmitcenterId,localPart=test,domain=…— oder ohne CenterlocalPart=dmarc,domain=cockpit-os.de- Webmail unter
https://mail.cockpit-os.demit der einmaligen Response-Adresse und dem Passwort prüfen. cockpit_create_mail_aliasz. B.localPart=gewinnspiel,target=bestehende Adresse auf der Center-Domain — sofort aktiv.- Externes Ziel (z. B. Gmail): Antwort
verificationRequired=true. Bestätigungsmail öffnen, Button klicken. Reiter zeigt Bestätigung offen bis dahin.cockpit_resend_mail_alias_verificationbei Bedarf. cockpit_list_mailboxes— cockpitOS-Inventar (Quota-Nutzung wird vom Mail-Anbieter ergänzt, falls konfiguriert).cockpit_list_mail_aliases— Standard: cockpitOS-Inventar; mit QueryincludeMailcow=truezusätzlich Anbieter-Aliase (siehe AgencyOS-Antwortfelder in der API-Doku).- Formular:
POST …/send-contact-inquirymitrecipientEmail=info@…oderformKey=localPart— Resend stellt zu, mailcow empfängt. Unbestätigte Aliase stehen nicht auf der Allowlist. cockpit_mail_dns_plan— Warnings lesen (fremder MX?). Danncockpit_mail_dns_applyzuerst ohnedryRun=false, danach mitconfirm=true.- Dashboard: Center öffnen → Reiter E-Mail. Postfach anlegen oder Neues Passwort. Outlook-Daten stehen im Reiter. DNS-Setzen bleibt Betrieb.
- Admin:
cockpit_mailcow_admin_status—viaApi.uiTextsundappLinkstrue,logo/sogoBrandingfalse. UI-Texte nur setzen, wenn die gewünschten Werte feststehen undconfirm=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.
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: /en/developer-guide/center-mail-provisioning