Inbound Mailboxes API

Ein Postfach verbindet eine E-Mail-Adresse mit dem Helpdesk: Eviworx ruft es ab, macht aus jeder Mail einen Vorgang und schickt Antworten über denselben Weg zurück. Jedes Postfach bringt seine eigene Konfiguration mit — Empfangs- und Sendeweg, Standardwerte für neue Tickets, Grenzen, Nachbehandlung im Postfach und optional eine Zugriffsbeschränkung. Verwaltet wird das alles unter /api/inbound-mailboxes. Wie der Weg einer Mail durch das System läuft, steht auf der Seite E-Mail-System.

📮

Funktionen

✓ Beliebig viele Postfächer nebeneinander

✓ IMAP oder Microsoft Graph beim Empfang

✓ SMTP oder Microsoft Graph beim Versand

✓ Standardwerte je Postfach für neue Tickets

✓ Grenzen je Postfach statt global

✓ Verbindungsprobe und Ordnerliste live

✓ Zugriffsbeschränkung je Postfach

✓ Rückstand und Fehlergrund im Betriebszustand

Rechte

Permission	Erlaubt
`inboundMailboxes.view`	Postfächer und ihren Betriebszustand lesen
`inboundMailboxes.create`	Postfach anlegen
`inboundMailboxes.edit`	Postfach ändern und die Ordnerliste des Servers abfragen
`inboundMailboxes.delete`	Postfach löschen — kritisches Recht (Entzug wirkt sofort, verweigerte Aufrufe werden protokolliert)
`inboundMailboxes.testConnection`	Empfangsweg prüfen
`inboundMailboxes.testSmtp`	Sendeweg prüfen
`inboundMailboxes.manageAccess`	Zugriffsbeschränkung setzen und Freigaben vergeben — kritisches Recht, weil es die Ticket-Sicht über alle Postfächer hinweg öffnet
`tickets.changeMailbox`	Ein Ticket in ein anderes Postfach übergeben; öffnet zusätzlich die Auswahlliste aller aktiven Postfächer

Endpoints

Methode	Endpoint	Antwort	Permission
`GET`	`/api/inbound-mailboxes`	Alle Postfächer — { data }, neueste zuerst; enthält auch deaktivierte	`view`
`GET`	`/api/inbound-mailboxes/options`	Schlanke Auswahlliste — { data } mit id, name, emailAddress	jede Anmeldung
`GET`	`/api/inbound-mailboxes/:id`	Ein Postfach	`view`
`POST`	`/api/inbound-mailboxes`	Anlegen → 201	`create`
`PUT`	`/api/inbound-mailboxes/:id`	Ändern — Teiländerung erlaubt	`edit`
`DELETE`	`/api/inbound-mailboxes/:id`	Löschen → 204	`delete`
`POST`	`/api/inbound-mailboxes/:id/test-connection`	Empfangsweg prüfen → { connected: true }	`testConnection`
`POST`	`/api/inbound-mailboxes/:id/test-smtp`	Sendeweg prüfen → { connected: true }	`testSmtp`
`GET`	`/api/inbound-mailboxes/:id/folders`	Ordner des Servers — { data } mit Ordnerpfaden	`edit`
`GET`	`/api/inbound-mailboxes/:id/restriction`	{ mailboxId, isRestricted }	`view`
`PUT`	`/api/inbound-mailboxes/:id/restriction`	Beschränkung ein-/ausschalten → { mailboxId, isRestricted }	`manageAccess`
`GET`	`/api/inbound-mailboxes/:id/access`	{ mailboxId, isRestricted, accessList }	`manageAccess`
`POST`	`/api/inbound-mailboxes/:id/access`	Freigabe vergeben → 201	`manageAccess`
`DELETE`	`/api/inbound-mailboxes/:id/access/:accessId`	Freigabe entziehen → 204	`manageAccess`

Lesen und Prüfen stehen auch API-Keys offen; alle Mutationen verlangen eine angemeldete Person und antworten einem API-Key mit 403. Die Auswahlliste ist die Ausnahme unter den Lesewegen: ihr Zuschnitt ist benutzerbezogen, deshalb ist auch sie benutzergebunden.

Die Liste kennt weder Filter noch Seiten — es sind wenige Einträge, und die Verwaltung braucht alle. Löschen ist ein Soft-Delete: das Postfach verschwindet aus jeder Antwort und wird nicht mehr abgerufen; eine Wiederherstellung über die API gibt es nicht.

Auswahlliste

GET /options liefert nur id, name und emailAddress aktiver Postfächer und braucht kein eigenes Recht — den Schutz macht der Zuschnitt. Der Parameter for entscheidet, welcher:

`for`	Enthält
fehlt (Standard)	Postfächer, deren Tickets der Aufrufer sehen darf — die Grundlage für Filter
`create`	Postfächer, aus denen er senden darf; eine Teilmenge der ersten Menge
`transfer`	alle aktiven Postfächer als Übergabeziele — bewusst nicht auf die eigene Sicht beschränkt und deshalb mit tickets.changeMailbox gegated

Ein anderer Wert für for wird mit 400 abgewiesen, statt still auf den Standard zurückzufallen: ein Tippfehler in einer Integration soll auffallen und nicht eine engere Liste liefern als gedacht. Unbeschränkte Postfächer sind immer enthalten.

Das Postfach-Objekt

Identität und Wege

Feld	Bedeutung
`name`	Anzeigename, 1–100 Zeichen
`emailAddress`	Die Adresse des Postfachs; systemweit eindeutig (409 bei Doppelbelegung)
`protocol`	`IMAP` · `MS_GRAPH` — Empfangsweg
`receiveConfig`	Zugangsdaten des Empfangswegs, passend zum Protokoll
`sendProtocol`	`SMTP` · `MS_GRAPH` — Sendeweg
`sendConfig`	Zugangsdaten des Sendewegs; leeres Objekt = das Postfach empfängt nur
`fromName`	Absendername; leer ⇒ der Anwendungsname aus den Oberflächen-Einstellungen
`replyToAddress`	Antwortadresse; leer ⇒ die Postfach-Adresse
`hasReceiveCredentials` · `hasSendCredentials`	Ist ein Passwort bzw. Client-Secret hinterlegt? Die Geheimnisse selbst liest die API nie zurück
`signatureId`	Signatur, die ausgehenden Mails dieses Postfachs angehängt wird
`checkIntervalMin`	Abrufintervall in Minuten, 1–60 (Standard 5)
`isActive`	Wird abgerufen und darf senden. Ein deaktiviertes Postfach holt keine Mails und lehnt den Versand mit 400 SOURCE_MAILBOX_INACTIVE ab

Was aus einer Mail wird

Feld	Bedeutung
`mode`	`TICKET` immer ein Ticket · `EMAIL_CONVERSATION` eine E-Mail-Konversation · `AUTO` Ticket, wenn der Absender ein Konto hat, sonst Konversation. Die Antwort zeigt immer den eingestellten Wert, nicht den je Absender aufgelösten
`unknownSenderPolicy`	`AUTO_CREATE` Kontakt anlegen · `CATCH_ALL` alles einem Sammel-Konto zuschreiben · `REJECT` ablehnen
`catchAllUserId`	Das Sammel-Konto; bei CATCH_ALL Pflicht (sonst 400)
`defaultCategoryId` · `defaultGroupId` · `defaultPriority`	Vorbelegung neuer Tickets. Die Gruppe muss Tickets führen (sonst 400), Priorität aus LOW, MEDIUM, HIGH, URGENT, CRITICAL
`subjectPrefix`	Kürzel im Betreff, 1–10 Zeichen; der Betreff trägt dann [Kürzel-Ticketnummer]
`autoReplyEnabled`	Eingangsbestätigung an den Absender
`enforceSpf` · `enforceDkim` · `enforceDmarc`	Absender-Prüfungen erzwingen; eine nicht bestandene Prüfung führt zur Ablehnung
`bounceDetection`	Schalter für die Behandlung von Unzustellbarkeits- und Abwesenheitsmeldungen am Postfach

Nachbehandlung im Postfach

Feld	Bedeutung
`processedAction`	`MARK_READ` · `MOVE` · `DELETE` — was mit einer verarbeiteten Mail im Postfach geschieht
`processedFolder`	Zielordner bei MOVE; dann Pflicht (sonst 400)
`rejectedFolder`	Ordner für abgelehnte Mails, Standard Rejected. Abgelehnte Mails werden verschoben, nie gelöscht — ohne Ordner bleibt nur das Markieren als gelesen

Grenzen je Postfach

Feld	Standard	Wirkung
`rateLimitPerMinute`	60	Mails je Minute aus diesem Postfach, 1–1000
`rateLimitPerSenderPerHour`	30	Mails je Absender und Stunde, 1–1000
`autoCreateDailyLimit`	100	Automatisch angelegte Kontakte je Tag, 1–10000. Erreicht das Postfach die Grenze, antwortet der Anlegeweg mit 429 und einem Retry-After bis Mitternacht (UTC) — die Mail bleibt offen und wird danach verarbeitet

Betriebszustand (nur lesend)

Feld	Bedeutung
`lastCheckedAt`	Letzter Abruf-Versuch
`lastSuccessfulCheckAt`	Letzter erfolgreicher Abruf; bleibt bei einem Fehler stehen
`lastErrorCode`	Grund des letzten Fehlers als Code (siehe unten); null = kein Fehler. Der Code bleibt auch dann gesetzt, wenn nur die Nachbehandlung einer einzelnen Mail scheiterte
`consecutiveErrors`	Fehler in Folge; nach einem Erfolg 0
`openMailCount`	Rückstand: entdeckte, noch nicht erledigte Mails
`oldestOpenSince`	Seit wann die älteste offene Mail wartet
`accessRestricted`	Ist die Zugriffsbeschränkung aktiv?

Diese Felder schreibt jeder Abruf neu — sie heilen sich selbst. Denselben Zustand wertet der Systemstatus aus: ein Postfach ohne Abruf, eines mit Fehlern und eines mit zu altem Rückstand melden je einen eigenen Grund.

Empfangs- und Sende-Konfiguration

Fall	Felder	Voreinstellung
`receiveConfig`, `IMAP`	`host`, `port`, `security` (`none` · `tls` · `ssl`), `username`, `password`, `folder`, `tlsVerify`	`port 993`, `security ssl`, `folder INBOX`, `tlsVerify true`
`receiveConfig`, `MS_GRAPH`	`tenantId`, `clientId`, `clientSecret`, `userPrincipal`, `folder`	`folder inbox`
`sendConfig`, `SMTP`	`host`, `port`, `security`, `username` (optional), `password`, `tlsVerify`	`port 587`, `security tls`, `tlsVerify true`
`sendConfig`, `MS_GRAPH`	`tenantId`, `clientId`, `clientSecret`, `userPrincipal`	—

Passwort und Client-Secret gehen nur hinein, nie heraus: sie werden verschlüsselt gespeichert, und die Antwort zeigt statt ihrer nur, ob eines hinterlegt ist. Wer beim Ändern kein Geheimnis mitschickt, behält das gespeicherte. tenantId und clientId sind Azure-Kennungen, userPrincipal ist eine E-Mail-Adresse.

Ordnerpfade

Empfangsordner, Ordner für verarbeitete und Ordner für abgelehnte Mails werden gleich geschrieben: als Anzeigenamen, verschachtelte Ebenen mit Schrägstrich getrennt — Support/Erledigt. Diese Schreibweise gilt für beide Protokolle; die Übersetzung in die Trennzeichen und Namensräume des jeweiligen Servers übernimmt Eviworx. Gängige Namen wie INBOX oder inbox werden unabhängig von Groß- und Kleinschreibung erkannt. Den Empfangsordner muss es geben — er wird nur gesucht, nie angelegt; die Zielordner für verarbeitete und abgelehnte Mails legt Eviworx bei Bedarf selbst an. Welche Ordner der Server anbietet, zeigt die Ordnerliste.

Anlegen und Ändern

Beide Wege nehmen ausschließlich bekannte Felder an — ein unbekanntes Feld wird mit 400 abgewiesen, statt still ignoriert zu werden.
Die Konfiguration wird nach dem gewählten Protokoll geprüft: ein IMAP-Postfach braucht IMAP-Felder, ein Graph-Postfach Graph-Felder. Fehlermeldungen benennen den Pfad des Feldes, etwa receiveConfig.host.
Fehlt beim Anlegen die Sende-Konfiguration oder ist sie leer, empfängt das Postfach nur. Es gibt keinen stillen Rückfall auf einen globalen Versandweg.
Eine Teiländerung ändert genau die gesendeten Felder und setzt nichts anderes zurück. Konfigurations-Objekte dürfen ebenfalls teilweise kommen und werden mit dem Bestand zusammengeführt.
Wer das Protokoll wechselt, muss die passende Konfiguration mitsenden (sonst 400) — und sie wird dann nicht mit der alten zusammengeführt. Das schließt die Lücke „neues Protokoll, alte Zugangsdaten".
Eine leere Sende-Konfiguration beim Ändern entfernt den Versand: das Postfach empfängt danach nur noch.
Abhängigkeiten werden am Ergebnis geprüft, nicht an der Anfrage: ein Sammel-Konto muss auch dann vorhanden sein, wenn nur die Absender-Regel geändert wird.

Sendefähigkeit

Ob ein Postfach senden kann, entscheidet eine Regel für alle Wege — Verbindungsprobe, Ticket-Antwort und „Ticket als E-Mail". Sie richtet sich danach, was der Versand tatsächlich braucht:

Zustand	Ergebnis
keine Sende-Konfiguration	`RECEIVE_ONLY`
SMTP ohne Benutzernamen	sendefähig — ein Relay ohne Anmeldung ist ein gültiger Aufbau
SMTP mit Benutzernamen, Passwort hinterlegt	sendefähig
SMTP mit Benutzernamen, ohne Passwort	`NO_CREDENTIALS`
Microsoft Graph mit Client-Secret	sendefähig
Microsoft Graph ohne Client-Secret	`NO_CREDENTIALS`

Ist ein Postfach nicht sendefähig, antworten die Sende-Wege mit 400 MAILBOX_SEND_NOT_CONFIGURED und nennen in details.reason den Grund — und zwar bevor eine Nachricht angelegt wird, damit keine Spur „Antwort gesendet" für eine Mail entsteht, die nie hinausging. Die Verbindungsprobe fragt bewusst nur die Konfiguration ab, nicht den Aktiv-Schalter: ein Postfach lässt sich vor seiner Aktivierung prüfen. Am Ticket zeigt sendConfigured im Postfach-Verweis denselben Wert, den das Gate verwendet — die Oberfläche kann den Antwort-Knopf damit sperren, statt den Fehler abzuwarten.

Proben: Verbindung und Ordnerliste

Beide Proben laufen über denselben Weg wie der Betrieb: dieselben Zugangsdaten, derselbe Adapter, dieselbe Ordner-Auflösung. Eine Probe bestätigt damit wirklich den produktiven Weg und nicht eine eigene Test-Verbindung.

POST /api/inbound-mailboxes/:id/test-connection
POST /api/inbound-mailboxes/:id/test-smtp
GET  /api/inbound-mailboxes/:id/folders

{ "connected": true }

{ "data": ["INBOX", "Support/Erledigt", "Rejected"] }

Ein Fehlschlag ist ein Fehler, keine Antwort mit connected: false: Status 400, und der Grund des Prüflaufs ist selbst der errorCode (die MAIL_*-Codes unten). details.message trägt eine englische Diagnose für den Support.
Fehlen die Zugangsdaten oder ist das Postfach gar nicht zum Senden eingerichtet, antwortet Eviworx sofort mit 400 — ohne den Mailserver zu kontaktieren.
Antwortet der E-Mail-Dienst binnen 20 Sekunden nicht, ist das ein Infrastruktur-Fall und kein Mail-Fehler: 503 EMAIL_WORKER_UNAVAILABLE. Die Prüfung selbst ist knapper gedeckelt, damit der Aufrufer die Diagnose sieht und nicht die Zeitgrenze.
Die Ordnerliste trägt das Recht edit, nicht view: sie beschafft Daten für das Bearbeiten-Formular.

Für den globalen Versand ohne Postfach-Bezug gelten die beiden Proben der Settings-API (/api/settings/email/test-smtp und /test-graph) — gleiche Antwortform, gleiche Fehlercodes.

Zugriffsbeschränkung

Standardmäßig ist ein Postfach offen: wer Tickets sehen darf, sieht auch die Tickets dieses Postfachs. Ein beschränktes Postfach dreht das um — dann sehen seine Tickets nur noch Personen mit einer Freigabe. Das ist der Weg für Postfächer wie personal@ oder abrechnung@, deren Vorgänge nicht das ganze Team betreffen.

Freigabe	Bedeutung
`userId` · `roleId` · `agentGroupId`	Genau eines davon je Freigabe: eine Person, alle mit einer Rolle oder eine Agentengruppe. Die Oberfläche bietet Person und Rolle an; die Gruppen-Freigabe ist ein reiner API-Weg
`canViewTickets`	Darf die Tickets dieses Postfachs sehen
`canBeAssigned`	Darf sie bearbeiten und daraus senden

Eine zweite Freigabe an dasselbe Ziel wird mit 409 abgewiesen.
Der Entzug einer Freigabe, die es nicht gibt, und der Entzug einer Freigabe eines anderen Postfachs antworten gleich (404 MAILBOX_ACCESS_ENTRY_NOT_FOUND) — die API verrät nicht, ob ein fremder Eintrag existiert.
Das Recht manageAccess trägt selbst den Vorrang über alle Beschränkungen: wer es hat, sieht die Tickets jedes Postfachs und kann ihnen zugewiesen werden. Deshalb ist es ein kritisches Recht.

Fehlercodes

Code	HTTP	Wann
`MAILBOX_NOT_FOUND`	404	Unbekanntes oder gelöschtes Postfach
`MAILBOX_EMAIL_EXISTS`	409	Adresse bereits belegt; details nennt die Adresse
`MAILBOX_CATCH_ALL_USER_REQUIRED`	400	Absender-Regel CATCH_ALL ohne Sammel-Konto
`MAILBOX_PROCESSED_FOLDER_REQUIRED`	400	Nachbehandlung MOVE ohne Zielordner
`AGENT_GROUP_NOT_FOUND`	404	Standard-Gruppe existiert nicht
`GROUP_ENTITY_TYPE_MISMATCH`	400	Standard-Gruppe führt keine Tickets
`TICKET_CATEGORY_NOT_FOUND`	404	Standard-Kategorie existiert nicht
`MAILBOX_RECEIVE_NOT_CONFIGURED`	400	Empfangs-Probe oder Ordnerliste ohne hinterlegte Zugangsdaten
`MAILBOX_SEND_NOT_CONFIGURED`	400	Postfach nicht sendefähig; details.reason nennt RECEIVE_ONLY oder NO_CREDENTIALS
`SOURCE_MAILBOX_INACTIVE`	400	Versand aus einem deaktivierten Postfach
`MAILBOX_ACCESS_ENTRY_NOT_FOUND`	404	Freigabe-Eintrag gehört nicht zu diesem Postfach oder existiert nicht
`USER_CREATION_LIMIT_EXCEEDED`	429	Tageslimit automatisch angelegter Kontakte erreicht; Retry-After bis Mitternacht (UTC)
`EMAIL_WORKER_UNAVAILABLE`	503	Der E-Mail-Dienst hat die Probe nicht beantwortet
`EMAIL_SYSTEM_DISABLED`	400	Nur globale Proben: der E-Mail-Kanal ist nicht aktiviert
`VALIDATION_ERROR`	400	Schema-Verstoß; details führt die betroffenen Feldpfade
`FORBIDDEN`	403	Recht fehlt — oder ein API-Key ruft einen benutzergebundenen Weg

Gründe eines Mail-Fehlers

Dieselben siebzehn Codes stehen an zwei Stellen: als errorCode einer fehlgeschlagenen Probe und als lastErrorCode am Postfach. Ein Blick auf die Liste sagt damit dasselbe wie eine Probe.

Code	Bedeutung
`MAIL_CONNECTION_FAILED`	Server nicht erreichbar (Name oder Verbindung)
`MAIL_TIMEOUT`	Zeitgrenze überschritten
`MAIL_TLS_FAILED`	TLS oder Zertifikat abgelehnt
`MAIL_AUTH_FAILED`	Anmeldung abgelehnt
`MAIL_CREDENTIALS_MISSING`	Kein Passwort oder Secret hinterlegt
`MAIL_PERMISSION_DENIED`	Die App-Berechtigung in Microsoft 365 reicht nicht
`MAIL_MAILBOX_NOT_FOUND`	Das angegebene Postfach gibt es dort nicht
`MAIL_FOLDER_NOT_FOUND`	Ordner nicht auflösbar oder nicht anlegbar
`MAIL_RATE_LIMITED`	Der Mailserver drosselt
`MAIL_RECIPIENT_REJECTED`	Empfänger abgelehnt
`MAIL_MESSAGE_TOO_LARGE`	Nachricht für den Server zu groß
`MAIL_MESSAGE_REJECTED`	Nachricht oder Absender abgelehnt
`MAIL_CONFIG_UNAVAILABLE`	Postfach inaktiv oder ohne den benötigten Weg
`MAIL_QUEUE_UNAVAILABLE`	Der Auftrag konnte nicht eingereiht werden
`MAIL_SEND_FAILED`	Versand gescheitert, ohne genaueren Grund
`MAIL_RECEIVE_FAILED`	Abruf gescheitert, ohne genaueren Grund
`MAIL_SEND_OUTCOME_UNKNOWN`	Der Versuch brach ab — die Mail kann draußen sein

Protokollierung

Vorgang	Eintrag
Anlegen	`CREATE` — mit Empfangs- und Sendeprotokoll
Ändern	`UPDATE` — alt/neu für jedes der 26 protokollierten Einzelfelder; von den Konfigurationen wird nur vermerkt, DASS sie berührt wurden, nie ihr Inhalt
Löschen	`DELETE`
Freigabe vergeben / entziehen	`MAILBOX_ACCESS_GRANTED` · `MAILBOX_ACCESS_REVOKED` — mit Ziel und den beiden Flags
Beschränkung ein-/ausschalten	`MAILBOX_RESTRICTION_ENABLED` · `MAILBOX_RESTRICTION_DISABLED` — nur bei echtem Wechsel

Jede Änderung an einem Postfach erreicht den E-Mail-Dienst sofort: er lädt die Postfächer neu, ohne auf den nächsten Abruf zu warten. Ein deaktiviertes Postfach hört damit unmittelbar auf, Mails zu holen.