Postfach-Anbindung

Der invoiceR holt Rechnungen per IMAP aus einem Postfach ab. Diese Seite beschreibt, wie das Postfach technisch angebunden wird. Einen Überblick über Versand und Import findest du unter E-Mail-Versand und -Import.

Wie der Import funktioniert

1. Ein wiederkehrender Job prüft das Postfach in einem festen Takt (typischerweise alle paar Minuten).
2. Jede neue E-Mail im Eingangsordner wird registriert und in den Ordner Received verschoben.
3. Enthält die E-Mail genau ein PDF (oder keines), legt der invoiceR einen Import-Eintrag an und startet den Beleg-Import. Die E-Mail wandert nach Imported.
4. Enthält sie mehrere PDFs, wandert sie nach ManualProcessing. Klappt der Import nicht, nach Aborted.

Die Ordner legst du im Postfach als Unterordner des Posteingangs an, bevor du den Import startest.

Anmeldeverfahren

Verfahren	Wann verwenden
Client-Credential-Flow (OAuth, App mit Client-Secret)	Empfohlen für Microsoft 365. Kein Benutzerpasswort nötig.
Password-Flow (OAuth mit Benutzername und Passwort)	Nur wenn der Client-Credential-Flow nicht möglich ist. Das Postfach-Konto darf keine Mehrfaktor-Anmeldung haben.
Basic Authentication (Benutzername und Passwort direkt am IMAP-Server)	Für eigene IMAP-Server ausserhalb von Microsoft 365.

Basic Authentication bei Microsoft 365

Microsoft hat Basic Authentication für Exchange Online abgeschaltet. Für Postfächer in Microsoft 365 funktioniert nur noch OAuth (Client-Credential-Flow oder Password-Flow).

Hinweis

Für die Anmeldung mit OAuth muss der invoiceR-Server die Adressen outlook.office365.com und login.microsoftonline.com erreichen können.

Microsoft 365 mit Client-Credential-Flow

App in Microsoft Entra ID vorbereiten

1. Lege eine App-Registrierung an und notiere Tenant ID, Application (client) ID und den Wert des Client Secret.
2. Füge unter API permissions > Add a permission > APIs my organization uses die API Office 365 Exchange Online hinzu und wähle die Anwendungsberechtigung IMAP.AccessAsApp.
3. Erteile mit Grant admin consent die Administrator-Zustimmung.
4. Öffne unter Enterprise applications dieselbe App und notiere dort die Object ID. Das ist die Objekt-ID des Dienstprinzipals, nicht die der App-Registrierung.

App im Postfach berechtigen

Damit die App auf das Postfach zugreifen darf, registrierst du sie in Exchange Online und gibst ihr Zugriff. Öffne dazu PowerShell als Administrator:

Install-Module -Name ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName admin@contoso.ch

# Dienstprinzipal in Exchange bekannt machen
New-ServicePrincipal -AppId <application-id> -ServiceId <enterprise-app-object-id>

# Pro Postfach, aus dem importiert wird
Add-MailboxPermission -Identity "rechnungen@contoso.ch" -User <enterprise-app-object-id> -AccessRights FullAccess

Versand auf bestimmte Postfächer einschränken

Hat die App zusätzlich die Berechtigung Mail.Send (für den Versand über Microsoft Graph), dürfte sie im Namen jedes Postfachs senden. So schränkst du das ein:

1. Lege im Exchange Admin Center eine E-Mail-aktivierte Sicherheitsgruppe an und nimm nur die Postfächer auf, aus denen der invoiceR senden darf.
2. Erstelle die Richtlinie und prüfe sie:

New-ApplicationAccessPolicy -AppId <application-id> -PolicyScopeGroupId invoicer-versand@contoso.ch `
  -AccessRight RestrictAccess -Description "invoiceR darf nur aus dieser Gruppe senden"

Test-ApplicationAccessPolicy -Identity rechnungen@contoso.ch -AppId <application-id>

Microsoft 365 mit Password-Flow

1. Lege eine App-Registrierung an und notiere Tenant ID und Application (client) ID. Ein Client Secret brauchst du nicht.
2. Aktiviere unter Authentication die Option Allow public client flows.
3. Füge unter API permissions delegierte Berechtigungen für Microsoft Graph hinzu (email, offline_access, IMAP.AccessAsUser.All, User.Read) und erteile die Administrator-Zustimmung.
4. Stelle sicher, dass für das Postfach-Konto keine Mehrfaktor-Anmeldung verlangt wird.

Der invoiceR meldet sich dann mit Benutzername und Passwort des Postfachs an und holt dafür ein OAuth-Token.

Konfiguration im invoiceR

Die Einstellungen für den Import stehen als JSON in der Tabelle conf.IrManagers, im Eintrag mit dem ClassIdentifier invoiceR.PreSort.PreSortManager (Spalte Configuration). Diesen Eintrag richtet in der Regel enio ein. Beispiel für Microsoft 365 mit Client-Credential-Flow:

{
  "TempFolder": "D:\\invoiceR\\MailImport",
  "SaveAttachments": false,
  "Mail": {
    "Imap": {
      "HostName": "outlook.office365.com",
      "Port": 993,
      "UseSsl": true,
      "UserName": "rechnungen@contoso.ch",
      "UseOAuth": true,
      "OAuthTenantId": "<tenant-id>",
      "OAuthClientId": "<application-id>",
      "OAuthClientSecret": "<client-secret>"
    }
  },
  "CommonMail": {
    "InboxFolder": "INBOX"
  },
  "DefaultImportValues": {
    "MandatorCode": "100",
    "ProcessType": "GK",
    "InvoiceType": "R"
  }
}

Verbindung (Mail.Imap)

Schlüssel	Bedeutung
HostName, Port	IMAP-Server und Port, bei Microsoft 365 outlook.office365.com und 993.
UseSsl	Verbindung verschlüsselt aufbauen.
UseStartTls	Unverschlüsselte Verbindung mit STARTTLS auf TLS umstellen.
IgnoreCertificate	Zertifikatsfehler ignorieren (zum Beispiel selbst signierte Zertifikate). Nur im Notfall verwenden.
UserName	Postfach-Adresse.
Password	Passwort, nur bei Password-Flow und Basic Authentication.
IsSharedMailbox	true für ein freigegebenes Postfach mit Basic Authentication, dann lautet der Benutzername admin@contoso.ch\postfach.
UseOAuth	true für Microsoft 365.
OAuthTenantId, OAuthClientId	Tenant ID und Application ID der App-Registrierung.
OAuthClientSecret	Gesetzt: Client-Credential-Flow. Leer: Password-Flow.

Postfach-Ordner (CommonMail)

Schlüssel	Standard	Inhalt
InboxFolder	INBOX	Ordner, in dem neue E-Mails gesucht werden.
ReceivedFolder	INBOX/Received	E-Mails, die registriert und in Bearbeitung sind.
ImportedFolder	INBOX/Imported	Erfolgreich importierte E-Mails.
ManualProcessingFolder	INBOX/ManualProcessing	E-Mails mit mehreren PDFs, die jemand von Hand bearbeiten muss.
AbortedFolder	INBOX/Aborted	E-Mails, deren Import fehlgeschlagen ist.

Weitere Einstellungen

Schlüssel	Bedeutung
TempFolder	Ordner auf dem Server, in dem die PDFs für den Import abgelegt werden.
SaveAttachments	true speichert auch die übrigen Anhänge neben dem PDF.
DefaultImportValues	Vorgaben für den neuen Beleg: MandatorCode, ProcessType, InvoiceType, CostCentreCode, SupplierCode, DeleteImportFile.
MetadataAttachmentContainsFilter	Enthält ein Anhang diesen Text im Dateinamen (Standard meta), liest der invoiceR ihn als JSON mit Zusatzdaten.
PropertyMappings	Ordnet Werte aus dieser JSON-Datei Feldern des Imports zu (IrCaseImportPropertyName, JsonSelectTokenPath, DataType).

Job einrichten

Den Abruf startet der Job Run Email Check in conf.IrRecurringJobs mit ClassIdentifier enio.tool.Plugin.CheckMailbox.RunEmailCheck, MethodName DoCheck und MethodArgumentIdentifier enio.tool.Plugin.CheckMailbox.RunEmailCheckArgument. Wie Jobs angelegt werden, steht unter Wiederkehrende Jobs.

Conextrade

E-Rechnungen über Conextrade (Swisscom) kommen nicht über ein Postfach, sondern über einen eigenen Import-Job, der die Rechnungen per SFTP abholt (InvoiceR Conextrade Import). Diesen Job richtet enio zusammen mit den Zugangsdaten von Conextrade ein.

Fehler suchen

• Den Verlauf jedes Abrufs siehst du im Hangfire Dashboard (Administration > Hangfire Dashboard) beim Job Run Email Check.
• Liegen E-Mails in Aborted, steht der Grund im Job-Protokoll. Häufig fehlt der Zugriff auf TempFolder oder ein Pflichtwert in DefaultImportValues.
• Meldet die Anmeldung einen Fehler, prüfe zuerst, ob das Client Secret abgelaufen ist.