E-Mail-Konten (Mail Accounts)

Zweck

E-Mail-Konten verbinden ein Microsoft-365-Postfach mit SpeamCore. Pro Mailbox synchronisiert das System eingehende und ausgehende E-Mails ab einem konfigurierbaren Stichtag und ordnet sie ggf. den verknuepften Mitarbeitern zu. Sie sehen die Konten unter /mail-accounts (nicht /mailboxes — die FE-Route weicht vom BE-Pfad ab).

Voraussetzungen

- Es existiert mindestens eine **MicrosoftConfig** im System (zentral hinterlegte Microsoft-Tenant-Daten). - Anwender besitzt einen Microsoft-365-Account mit ausreichenden Rechten (Mail.Read, Mail.Send, Mail.ReadWrite). - Berechtigung `create:Mailbox` zum Anlegen.

Berechtigungen (CASL)

Frontend-Page-Guard:

Action	Subject	Keycloak-Rolle
view	FE_MailAccount	—
view	Mailbox	APP_SPEAMCORE_VIEW_MAILBOX

Tab-Subjects:

Tab	Sub-Pfad	Subject
Mitarbeiter	/mail-accounts/:id/employees	MailboxEmployee:view

API-Datenzugriff:

Action	Subject	Endpoint	Keycloak-Rolle
view	Mailbox	GET /api/mailboxes, GET /api/mailboxes/:id	APP_SPEAMCORE_VIEW_MAILBOX
create	Mailbox	POST /api/mailboxes (intern durch OAuth-Modal getriggert)	APP_SPEAMCORE_CREATE_MAILBOX
update	Mailbox	PATCH /api/mailboxes/:id	APP_SPEAMCORE_UPDATE_MAILBOX
delete	Mailbox	DELETE /api/mailboxes/:id	APP_SPEAMCORE_DELETE_MAILBOX

Schritt-für-Schritt-Anleitung

Mailbox neu verbinden

1. E-Mail-Konten (/mail-accounts) → Connect Microsoft 365.
2. Es öffnet sich der MicrosoftConfigModal — der vollständige OAuth-Flow gegen den Microsoft-Tenant.
3. Sie werden nach der Tenant-Auswahl auf eine Microsoft-Login-Seite umgeleitet.
4. Nach Zustimmung kommen Sie zurück zu SpeamCore. Die neue Mailbox wird angelegt und die Detail-Seite öffnet sich automatisch.
5. Pflegen Sie auf der Detail-Seite die Sync-Optionen (siehe Felder und Eingaben).

Mailbox bearbeiten

Auf der Detail-Seite koennen Sie den Sync-Stichtag, das Trash-Verhalten und den Aktiv-Status ändern. emailAddress und displayName sind read-only — sie werden aus Microsoft Graph übernommen und laufen über den Microsoft-Tenant.

Mailbox löschen

Loescht die SpeamCore-seitige Verknuepfung und die synchronisierten E-Mails. Das Microsoft-Konto selbst wird nicht gelöscht.

UI-Elemente

Button: „Connect Microsoft 365"

Listenseite. Erfordert create:Mailbox. Öffnet den MicrosoftConfigModal (~36 KB FE-Modul). Der Modal fuehrt durch den Microsoft-OAuth-Flow und legt nach Erfolg automatisch eine Mailbox an.

Wirkung: Erzeugt einen neuen Mailbox-Datensatz mit microsoftConfigId, microsoftUserId, emailAddress, displayName. Initial isActive = true, syncFromDate = heute.

Tab: „General Data"

Standard-Tab — zeigt das Mailbox-Form.

Tab: „Employees" (/mail-accounts/:id/employees)

Listet alle MailboxEmployee-Verknuepfungen. Erfordert MailboxEmployee:view. Tab ist sonst ausgeblendet.

Modal: MicrosoftConfigModal

Vollstaendiger OAuth-Wizard. Felder waehrend des Wizards: Tenant-Auswahl, Microsoft-Login-Redirect, Berechtigungs-Bestätigung. Nach Erfolg navigiert das System auf /mail-accounts/<neueId>.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Beschreibung	Wirkung beim Ausfuellen	Voraussetzung
emailAddress	—	E-Mail	Primaere E-Mail des Postfachs. Disabled im FE — Wert kommt aus Microsoft Graph.	Wird beim Versand aus SpeamCore als Absender genutzt. Änderung nur via Microsoft 365 selbst.	OAuth-Verbindung mit Mailbox-Berechtigung.
displayName	—	String	Anzeigename des Postfachs. Disabled im FE — Wert kommt aus Microsoft Graph.	Erscheint in Auswahl-Listen und im E-Mail-Header.	Wie oben.
isActive	nein	Auswahl active/inactive	Steuert, ob die Mailbox aktiv synchronisiert wird.	active: Sync laeuft regelmaessig, neue Mails landen in SpeamCore. inactive: Sync pausiert, bestehende E-Mails bleiben sichtbar.	—
syncFromDate	nein	Datum	Stichtag, ab dem E-Mails synchronisiert werden.	E-Mails vor diesem Datum werden nicht in SpeamCore gespiegelt. Änderung wirkt erst beim nächsten Sync-Lauf.	Datum darf nicht in der Zukunft liegen.
moveToTrashAfterSync	nein	Boolean (Switch)	Wenn true: nach erfolgreichem Sync wird die E-Mail im Microsoft-Postfach in den Papierkorb verschoben.	Reduziert die Belastung des Microsoft-Postfachs (z. B. Mailbox-Limit), erhaelt aber Volltext in SpeamCore.	Microsoft-Postfach hat Move-to-Trash-Berechtigung.
microsoftConfigId	automatisch	UUID	Verknuepfung zur zentralen MicrosoftConfig.	Steuert Tenant- und Anwendungs-Konfiguration.	Wird vom OAuth-Modal gesetzt.
microsoftUserId	automatisch	String	Microsoft Graph User-ID.	Identifiziert das Postfach gegenueber der Microsoft-API.	Wird vom OAuth-Modal gesetzt.
mailDomainId	automatisch	UUID	Verknuepfung zur erkannten Mail-Domaene.	Wird für Domaen-spezifische Filter und Reports genutzt.	Wird vom OAuth-Modal gesetzt.

Workflows und Zustaende

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• MicrosoftConfig — zentrale Tenant-Konfiguration. Neue Mailboxen verweisen darauf.
• MailboxEmployee — Verknuepfung Mailbox ↔ Mitarbeiter (Tab Employees).
• Mail — eingehende und ausgehende E-Mails der Mailbox.
• Setup-Wizard Schritt 12 — initiale Mailbox-Anbindung.

Häufige Fehler und Lösungen

Fehler	Lösung
OAuth-Flow bricht ab	Pop-up-Blocker prüfen; Microsoft-Tenant-Admin muss SpeamCore als App freigeben.
emailAddress änderbar gewünscht	Per Design read-only — direkt im Microsoft-Konto ändern, dann nächster Sync übernimmt den Wert.
Synchronisation laeuft nicht	isActive = inactive setzen prüfen; ggf. Microsoft-Token abgelaufen — Mailbox neu verbinden.
Alte E-Mails fehlen	syncFromDate zu spaet gesetzt. Stichtag rueckdatieren und auf nächsten Sync warten.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/mailboxes	Liste	view Mailbox
GET	/api/mailboxes/:id	Detail	view Mailbox
POST	/api/mailboxes	Anlegen (intern durch OAuth-Modal)	create Mailbox
PATCH	/api/mailboxes/:id	Ändern	update Mailbox
DELETE	/api/mailboxes/:id	Löschen	delete Mailbox

Hinweis: Der OAuth-Flow ist nicht ein einzelner Endpoint, sondern eine Sequenz von Microsoft-Graph-Aufrufen plus POST /api/mailboxes als Abschluss.

Versionshinweise

• 2026-04-29: Initiale Veroeffentlichung. FE-Route /mail-accounts notiert (BE-Pfad bleibt /api/mailboxes).