# Connect mailboxes > A mailbox brings incoming mail into nexxus. Its attachments land in Files, it starts AI schedules, and the AI Assistant can answer it. How to connect an IMAP mailbox, including Microsoft 365, or have Postal deliver. 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](/use/assistant/#ask-the-ai-assistant-by-email). ## 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](/setup/invite-users/#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](#microsoft-365-sign-in-through-an-app-registration). - **Postal**: a Postal server delivers every mail directly. You need access to its routing. ## Create a mailbox 1. Open 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](#postal-delivery-instead-of-polling). 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](#step-3-enter-it-in-nexxus). 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](/use/assistant/#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](#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 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: ```powershell Install-Module -Name ExchangeOnlineManagement Connect-ExchangeOnline -Organization New-ServicePrincipal -AppId -ObjectId -DisplayName "nexxus mailbox" $sp = Get-ServicePrincipal -Identity "nexxus mailbox" Add-MailboxPermission -Identity -User $sp.Identity -AccessRights FullAccess ``` If IMAP is switched off for the mailbox, switch it on: ```powershell Set-CASMailbox -Identity -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](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth), in the section on the client credentials flow. ### Step 3: enter it in nexxus 1. Create the mailbox as described [above](#create-a-mailbox), 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](#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. :::note[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