Mailbox connection

invoiceR collects invoices from a mailbox using IMAP. This page describes the technical connection of the mailbox. For an overview of sending and import see Sending and importing email.

How the import works

A recurring job checks the mailbox at a fixed interval (typically every few minutes).
Every new email in the inbox folder is registered and moved to the Received folder.
If the email contains exactly one PDF (or none), invoiceR creates an import entry and starts the document import. The email moves to Imported.
If it contains several PDFs, it moves to ManualProcessing. If the import fails, it moves to Aborted.

Create these folders as subfolders of the inbox before you start the import.

Authentication methods

Method	When to use
Client credential flow (OAuth, app with client secret)	Recommended for Microsoft 365. No user password needed.
Password flow (OAuth with user name and password)	Only if the client credential flow is not possible. The mailbox account must not require multi-factor sign-in.
Basic authentication (user name and password directly on the IMAP server)	For your own IMAP servers outside Microsoft 365.

Microsoft 365 with client credential flow

Preparing the app in Microsoft Entra ID

Create an app registration and note the Tenant ID, the Application (client) ID and the value of the Client Secret.
Under API permissions > Add a permission > APIs my organization uses, add the API Office 365 Exchange Online and select the application permission IMAP.AccessAsApp.
Grant admin consent with Grant admin consent.
Open the same app under Enterprise applications and note the Object ID shown there. This is the object ID of the service principal, not the one of the app registration.

Granting the app access to the mailbox

To let the app access the mailbox, register it in Exchange Online and grant access. Open PowerShell as administrator:

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

# Register the service principal in Exchange
New-ServicePrincipal -AppId <application-id> -ServiceId <enterprise-app-object-id>

# For each mailbox to import from
Add-MailboxPermission -Identity "invoices@contoso.ch" -User <enterprise-app-object-id> -AccessRights FullAccess

Restricting sending to specific mailboxes

If the app also has the Mail.Send permission (for sending through Microsoft Graph), it could send on behalf of any mailbox. To restrict this:

In the Exchange admin center, create a mail-enabled security group containing only the mailboxes invoiceR may send from.
Create the policy and test it:

New-ApplicationAccessPolicy -AppId <application-id> -PolicyScopeGroupId invoicer-sending@contoso.ch `
  -AccessRight RestrictAccess -Description "invoiceR may only send from this group"

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

Microsoft 365 with password flow

Create an app registration and note the Tenant ID and the Application (client) ID. You do not need a client secret.
Under Authentication, turn on Allow public client flows.
Under API permissions, add delegated permissions for Microsoft Graph (email, offline_access, IMAP.AccessAsUser.All, User.Read) and grant admin consent.
Make sure the mailbox account does not require multi-factor sign-in.

invoiceR then signs in with the mailbox user name and password and obtains an OAuth token.

Configuration in invoiceR

The import settings are stored as JSON in the table conf.IrManagers, in the entry with the ClassIdentifier invoiceR.PreSort.PreSortManager (column Configuration). enio usually sets up this entry. Example for Microsoft 365 with client credential flow:

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

Connection (`Mail.Imap`)

Key	Meaning
`HostName`, `Port`	IMAP server and port; for Microsoft 365 `outlook.office365.com` and `993`.
`UseSsl`	Use an encrypted connection.
`UseStartTls`	Upgrade an unencrypted connection to TLS with STARTTLS.
`IgnoreCertificate`	Ignore certificate errors (for example self-signed certificates). Use only as a last resort.
`UserName`	Mailbox address.
`Password`	Password, only for password flow and basic authentication.
`IsSharedMailbox`	`true` for a shared mailbox with basic authentication; the user name is then `admin@contoso.ch\mailbox`.
`UseOAuth`	`true` for Microsoft 365.
`OAuthTenantId`, `OAuthClientId`	Tenant ID and application ID of the app registration.
`OAuthClientSecret`	Set: client credential flow. Empty: password flow.

Mailbox folders (`CommonMail`)

Key	Default	Content
`InboxFolder`	`INBOX`	Folder checked for new emails.
`ReceivedFolder`	`INBOX/Received`	Emails that are registered and being processed.
`ImportedFolder`	`INBOX/Imported`	Successfully imported emails.
`ManualProcessingFolder`	`INBOX/ManualProcessing`	Emails with several PDFs that someone must process by hand.
`AbortedFolder`	`INBOX/Aborted`	Emails whose import failed.

Further settings

Key	Meaning
`TempFolder`	Folder on the server where the PDFs are stored for import.
`SaveAttachments`	`true` also saves the other attachments next to the PDF.
`DefaultImportValues`	Defaults for the new document: `MandatorCode`, `ProcessType`, `InvoiceType`, `CostCentreCode`, `SupplierCode`, `DeleteImportFile`.
`MetadataAttachmentContainsFilter`	If an attachment’s file name contains this text (default `meta`), invoiceR reads it as JSON with additional data.
`PropertyMappings`	Maps values from this JSON file to import fields (`IrCaseImportPropertyName`, `JsonSelectTokenPath`, `DataType`).

Setting up the job

The collection is started by the job Run Email Check in conf.IrRecurringJobs with ClassIdentifier enio.tool.Plugin.CheckMailbox.RunEmailCheck, MethodName DoCheck and MethodArgumentIdentifier enio.tool.Plugin.CheckMailbox.RunEmailCheckArgument. How to create jobs is described in Recurring jobs.

Conextrade

E-invoices through Conextrade (Swisscom) do not arrive through a mailbox but through a separate import job that collects the invoices via SFTP (InvoiceR Conextrade Import). enio sets up this job together with the access data from Conextrade.

Troubleshooting

You can see the history of each run in the Hangfire dashboard (Administration > Hangfire dashboard) for the job Run Email Check.
If emails end up in Aborted, the reason is in the job log. Often the access to TempFolder is missing or a required value in DefaultImportValues.
If sign-in fails, first check whether the client secret has expired.