Connect mailboxes

A mailbox in nexxus is an address whose mail nexxus reads. nexxus stores every new mail, files its attachments in a folder of your choice and hands it on: an AI schedule can react to it, or the AI Assistant answers it if you switch that on for the mailbox.

An example: Brandt & Söhne works with Microsoft 365. IT creates the mailbox reports@example.com and registers an app for it in Microsoft Entra. The office manager connects the mailbox in nexxus and switches on Assistant answers mails. From then on, project management sends a mail on Mondays saying “Please send the hours booked per project last week as Excel” and gets the table back as an attachment, worked out with their own rights. What this looks like for the person writing is described in Ask the AI Assistant by email.

1. Mail arrives

   nexxus polls the mailbox every minute, or Postal delivers at once.

2. Stored

   As the mailbox's service account, without duplicates.

3. Attachments filed

   In the folder you chose. Without a folder they are only listed.

4. Processed further

   An AI schedule takes it, or the AI Assistant answers.

Each mail is handled once: if a schedule takes it, the AI Assistant does not answer.

Before you start

• You have the system role ADMIN in nexxus. The page Mailboxes opens for administrators only.
• There is a service account the mailbox works as. Filed attachments belong to it, and its roles decide which folders it may file into. How to create one is described in Service accounts.
• You know how the mail comes in:
  • IMAP with a password: server, port, username and password of the mailbox.
  • Microsoft 365: Exchange Online takes no password over IMAP. The mailbox signs in through an app registration in Microsoft Entra. Someone who may register apps in Entra and grant rights in Exchange Online PowerShell sets this up, usually your IT. The steps are below.
  • Postal: a Postal server delivers every mail directly. You need access to its routing.

Create a mailbox

1. Open AdministrationContent & automationMailboxes and click Create mailbox. The page New mailbox opens in edit mode.

2. In the section Connection, enter a Name such as “Inquiries” and choose the Kind: IMAP mailbox or Forwarded by Postal. For Postal, continue further down.

3. Under Sign-in, choose how the mailbox signs in:

   • Username and password: enter Server, Port, Username and Password. Usual are port 993 with SSL/TLS (IMAPS) and port 143 with STARTTLS, switched with Encryption. nexxus never polls a mailbox unencrypted.
   • Microsoft 365 (app registration): nexxus fills in the Server outlook.office365.com if the field is empty. The Username is the mailbox address. You also enter Directory (tenant) ID, Application (client) ID and Client secret from Entra, see below.

   IMAP folder is the folder nexxus reads. Left empty, it is INBOX.

4. In the section Processing:

   • Receiving is set to Paused for a new mailbox. Leave it that way until the connection test has passed.
   • Choose the Service account. The list shows only accounts of the account type service account.
   • Use Choose folder to pick an Attachment folder if attachments should land in Files. Without a folder nexxus only lists the attachments (none, attachments are only listed).

5. In the section AI assistant, switch on Assistant answers mails if the AI Assistant should answer requests sent to this mailbox. Below it you set Requests per person and hour, between 1 and 100, with 5 as the default. What happens then is described in Ask the AI Assistant by email.

6. Click Save. The message Mailbox created confirms it, and the page shows the mailbox in read view.

7. Click Test connection. nexxus signs in with the stored data without fetching anything. If it works, you see something like “Connection ok: 12 mails, 3 unread”. Otherwise you see „Verbindung fehlgeschlagen:“ (connection failed) and the reason, see When something goes wrong.

8. Click Edit, set Receiving to Active and click Save.

9. Once for the whole installation, switch on regular polling: open AdministrationOperationsMaintenanceCron Jobs and set the job MAILBOX_POLLER to Active. nexxus creates it switched off. As long as it is off, only what you fetch with Poll now arrives.

Poll now fetches new mail at once, even while the mailbox is paused, and reports something like No new mails or “2 new mails received”. Under Received mails the page shows the last 25 mails of the mailbox. Clicking a row opens the recipients, the attachments with a link into Files, the text and, if the AI Assistant was involved, what it did with the mail.

Microsoft 365: sign-in through an app registration

Exchange Online refuses an IMAP sign-in with username and password. A mailbox at Microsoft 365 therefore signs in as an app: nexxus uses the directory ID, the application ID and the client secret to get an access token from Microsoft and signs in over IMAP with it. Nobody has to sign in for this, and no personal password is stored in nexxus.

The app needs two things for this: in Entra the application permission IMAP.AccessAsApp with admin consent, and in Exchange Online the right to exactly this mailbox. Without the second, it can sign in but cannot open a mailbox.

Step 1: register the app in Microsoft Entra

You do these steps in the Microsoft Entra admin center.

1. Open https://entra.microsoft.com and go to Entra ID › App registrations › New registration. Give the app a name your IT recognises, such as “nexxus mailbox”. Under Supported account types, choose Single tenant only. This app needs no redirect URI.

2. Open Certificates & secrets › Client secrets › New client secret. Copy the Value right away: Microsoft shows it only once. nexxus needs the value, not the Secret ID. Note the expiry date. Once the secret has expired, nexxus stops polling the mailbox.

3. Open API permissions › Add a permission › APIs my organization uses, search for Office 365 Exchange Online, choose Application permissions, tick IMAP.AccessAsApp and click Add permissions.

4. On the same page, click Grant admin consent for your directory. The permission must then show as granted.

5. On the Overview page, copy the Application (client) ID and the Directory (tenant) ID.

6. Open Entra ID › Enterprise applications, choose the same app and copy the Object ID from its Overview page. Careful: this is a different Object ID from the one on the app registration’s page. With the wrong one, the sign-in fails later.

Step 2: give the app the mailbox

You do these steps in Exchange Online PowerShell, with an account that may grant rights in Exchange Online. First you register the app as a service principal in Exchange, then you give it the mailbox:

Install-Module -Name ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <Directory (tenant) ID>

New-ServicePrincipal -AppId <Application (client) ID> -ObjectId <Object ID of the enterprise application> -DisplayName "nexxus mailbox"
$sp = Get-ServicePrincipal -Identity "nexxus mailbox"
Add-MailboxPermission -Identity <mailbox address> -User $sp.Identity -AccessRights FullAccess

If IMAP is switched off for the mailbox, switch it on:

Set-CASMailbox -Identity <mailbox address> -ImapEnabled $true

This way the app reaches only the mailboxes you give it with Add-MailboxPermission, not every mailbox of your organisation. Microsoft describes the procedure in Authenticate an IMAP, POP or SMTP connection using OAuth, in the section on the client credentials flow.

Step 3: enter it in nexxus

1. Create the mailbox as described above, with the Kind IMAP mailbox and the Sign-in Microsoft 365 (app registration). The field Password disappears, and the three fields for Entra appear instead.

2. Enter:

   Field	Value
   Server	outlook.office365.com, filled in if the field was empty. Port 993 with SSL/TLS (IMAPS)
   Username	The mailbox address, such as reports@example.com
   Directory (tenant) ID	The Directory (tenant) ID. The directory’s domain works too, such as company.onmicrosoft.com
   Application (client) ID	The Application (client) ID
   Client secret	The Value of the client secret

3. Click Save and then Test connection. If Microsoft refuses, nexxus names the reason in German, see When something goes wrong.

nexxus never shows the stored secret again. When you edit the mailbox, the field reads unchanged: leave it empty and nexxus keeps the secret, enter a new one and it replaces the old. This is also how you swap an expired secret.

Postal: delivery instead of polling

With a Postal server, nexxus polls nothing. Postal sends every mail at once to a receiving URL of nexxus and signs every delivery. nexxus accepts only deliveries with a valid signature.

1. Create the mailbox with the Kind Forwarded by Postal. Server, username and password do not exist then.

2. Postal key (JWKS) is the address where your Postal server publishes its signing keys. It must start with https://. Left empty, the Server default applies.

3. Choose service account and folder as above and click Save. Only now is the Receiving URL created. Copy it with Copy URL.

4. In Postal, create an HTTP endpoint under Routing with this URL, with the encoding Sent in the body as JSON and the format Delivered as the raw message, and point the route for the receiving address at it.

5. Test connection loads the keys from Postal and reports something like Postal key loaded (1). Signed deliveries are accepted.

Create new URL replaces the receiving URL, for example if it got into the wrong hands. The old one stops accepting mail at once, so update the route in Postal right after. A Postal mailbox set to Paused accepts no deliveries.

What happens behind the scenes

• Polling. While the job MAILBOX_POLLER is active, nexxus polls all active IMAP mailboxes every minute, up to 25 mails per mailbox and round. It reads only unread mails in the IMAP folder and marks each one as read once it is stored. If nexxus stops in between, the mail stays unread and comes again with the next poll. A mail whose Message-ID the mailbox already knows is not stored a second time.
• Service account. Every mail is stored and filed as the service account. If it is deleted or no longer a service account, nexxus polls nothing and writes the reason under Error.
• Attachments. With a folder they become documents in Files, without one they are only listed. nexxus lists attachments over 25 MB but does not read them.
• What comes next. Every new mail goes to the active AI schedules with the trigger On new email for this mailbox whose filters match. If none takes it and Assistant answers mails is on, nexxus checks whether the AI Assistant answers it.
• Credentials. nexxus stores password and client secret encrypted only and never shows them again. nexxus keeps the access token from Microsoft in memory and fetches a new one shortly before it expires. If Exchange Online refuses the sign-in, nexxus drops the token and fetches a fresh one on the next attempt.
• Deleting. A deleted mailbox accepts nothing any more, and a stored password is discarded. Received mails are kept.

For self-hosters

Scheduled jobs run only when app.disableCronJobs is false, which the production profile sets. The interval between polls is communication.mailbox.pollDelayMs (60000), the number of mails per round communication.mailbox.maxMailsPerPoll (25). The default for Postal key (JWKS) comes from communication.mailbox.postal.defaultJwksUrl (environment variable POSTAL_JWKS_URL). For Microsoft 365, nexxus needs outgoing connections to login.microsoftonline.com and outlook.office365.com.

When something goes wrong

Errors of the connection test follow „Verbindung fehlgeschlagen:“. Errors of polling show in the field Error and at the top of the page: The last poll failed: … The server messages exist in German only.

Message	What to do
„Microsoft 365 lehnt den geheimen Clientschlüssel ab. Eingetragen sein muss sein Wert, nicht die ID des Geheimnisses.“ (Microsoft 365 refuses the client secret; it must be its value, not the secret’s ID)	Enter the Value under Client secret, not the Secret ID. If the value can no longer be seen, create a new secret in Entra.
„Der geheime Clientschlüssel ist abgelaufen. Bitte in Entra einen neuen anlegen und hier eintragen.“ (the client secret has expired)	Create a new secret under Certificates & secrets and enter its value.
„Eine App mit dieser Anwendungs-ID (Client) gibt es in diesem Verzeichnis nicht.“ (no app with this application ID in this directory)	Check Application (client) ID and Directory (tenant) ID. The app must be registered in this directory.
„Microsoft kennt diese Verzeichnis-ID (Tenant) nicht.“ (Microsoft does not know this directory ID)	Enter the Directory (tenant) ID from the app’s overview page, or the directory’s domain.
„Exchange Online hat die IMAP-Anmeldung abgelehnt: Der App fehlt die Anwendungsberechtigung IMAP.AccessAsApp (Office 365 Exchange Online) mit Administratorzustimmung.“ (the app lacks the application permission IMAP.AccessAsApp with admin consent)	Add the permission and grant consent, see step 1, items 3 and 4. A delegated permission is not enough.
„Exchange Online hat die IMAP-Anmeldung abgelehnt. Hat die App Zugriff auf dieses Postfach (Dienstprinzipal in Exchange mit New-ServicePrincipal, Recht mit Add-MailboxPermission), und ist IMAP für das Postfach eingeschaltet?“ (Exchange Online refused the sign-in; does the app have access to this mailbox, and is IMAP on?)	Do step 2. Check that New-ServicePrincipal got the Object ID of the enterprise application and that IMAP is on for the mailbox.
„Bei Microsoft 365 ist der Benutzername die Adresse des Postfachs.“ (with Microsoft 365 the username is the mailbox address)	Enter the full address under Username.
„Ohne Passwort kann das Postfach nicht aktiv sein.“ or „Ohne geheimen Clientschlüssel kann das Postfach nicht aktiv sein.“ (without a password or client secret the mailbox cannot be active)	Enter the password or secret before setting Receiving to Active.
„Das Dienstkonto ist gelöscht oder kein Dienstkonto mehr.“ (the service account is deleted or no longer a service account)	Choose another Service account, or set the account type of the old one back to Service account.
„Die Adresse des Postal-Schlüssels (JWKS) muss mit https:// beginnen.“ (the Postal key address must start with https://)	Enter the HTTPS address or leave the field empty.
The test passes, but nothing arrives	The job MAILBOX_POLLER is off, or Receiving is set to Paused. Or the new mails have already been read: nexxus fetches unread mails only.

Next steps

Ask the AI Assistant by emailWho gets an answer, what it looks like and where you see the state of every mail.

Service accountsCreate the account a mailbox works as.

FilesWhere filed attachments land and who sees them.