Admin tab: Email mailboxes (IMAP/POP3/EWS/Microsoft 365)

In the Mailboxes admin tab (group Integrations) you set up email accounts that CompanyWizard uses as a source (import mail) and — if enabled — as a sending channel. This page is the configuration reference; what the feature does functionally is described in Email mailboxes.

Supported protocols

• IMAP – recommended for most mail servers.
• POP3 – simple retrieval without a server-side folder structure.
• EWS (Exchange Web Services) – for on-prem/hybrid Exchange.
• Microsoft 365 (Exchange Online) – via Microsoft Graph, without a password: the account is connected with an administrator’s Microsoft account. → Set up Microsoft 365

Fields per account

General: Name (technical ID), Display name, Protocol, Username, Password (leave empty when editing = unchanged), Enabled.

For IMAP/POP3: Host, Port, Use TLS (default on), Check certificate revocation (with TLS), Default folder (IMAP, e.g. INBOX), Timeout (5–300 s).

For EWS: Auth type (Password or NTLM), Domain (with NTLM), Service URL (e.g. https://mail.example.com/EWS/Exchange.asmx), Exchange version. If the service URL points to outlook.office365.com, the form suggests switching the account to Microsoft 365 — Microsoft is retiring EWS for Exchange Online.

For Microsoft 365: Mailbox address and Default folder (e.g. Inbox). Host, port, password and timeout do not apply. The mailbox address is optional: empty means your own mailbox — when you connect, CompanyWizard fills in your Microsoft account’s address. For a shared mailbox, enter its address.

Microsoft 365 (Exchange Online)

Prerequisite

Microsoft Graph is set up under Admin → System Settings → “Microsoft Graph / SharePoint”. → Set up Microsoft SharePoint

• Desktop: quick start (evanto app) or your own app.
• Web: only with your own app including a client secret. Without it, “Connect with Microsoft” in the form reports that the sign-in could not be started and names the reason.

On top of the SharePoint permissions the app needs the delegated permissions Mail.ReadWrite and Mail.ReadWrite.Shared (read, mark as read and move to an archive folder — in your own and in shared mailboxes) and Mail.Send and Mail.Send.Shared (send system mail through the mailbox, see below). An existing app registration of your own gets them without a trip to the Entra portal: run the provisioning assistant again on a Desktop (Admin → System settings → Microsoft → “Create registration automatically” or “Set up SharePoint for the website”). It adds the permissions and grants admin consent in the same run. → Provisioning assistant

Connect

1. Create the account with protocol Microsoft 365 (Exchange Online) and Save.
2. “Connect with Microsoft” — on the desktop the Microsoft sign-in opens (silently if you are already signed in); on the web you are redirected to Microsoft and land back in the Mailboxes tab afterwards.
3. The account shows “Connected with Microsoft”; check access with “Test connection”.

From then on the account runs on your Microsoft sign-in — also for agents and workflows that run without you. Another administrator takes it over by choosing “Reconnect with my Microsoft account” themselves.

Consent (administrator, organisation-wide)

Microsoft’s default consent policy (managed by Microsoft) explicitly excludes the mailbox permissions Mail.ReadWrite and Mail.ReadWrite.Shared from user consent — regardless of who publishes the app. → It cannot be done without an administrator In practice: an administrator (at least Cloud Application Administrator) ticks “Consent on behalf of your organization” in the consent dialog on the first connect.

As a fallback: if connecting fails for missing consent, the form shows the button “Grant access for your organization” below the message. It opens Microsoft’s consent page for exactly the app this installation signs in with; an administrator consents there once, then choose “Connect with Microsoft” again. With your own app, a hint on the provisioning assistant follows: the grant covers only permissions listed in the registration — if the mail permissions are not there yet, the assistant adds them first.

If you used the quick start before mailboxes, you will be asked for consent again when you first connect a mailbox — the evanto app now also requests the mail permissions.

Shared mailboxes

• The connected Microsoft account needs full access to the shared mailbox (Exchange admin center → Recipients → Mailboxes → select the mailbox → Delegation → Read and manage).
• Newly granted access takes about 15 minutes to become effective, sometimes longer. Until then the test reports “Mailbox or folder not reachable” — wait a little and test again.

Sending system mail through the mailbox

A connected Microsoft 365 mailbox can also send the system mail — sign-in codes, notifications and mail from the send tool — without any SMTP password. That is the way forward when Microsoft retires password sign-in for smtp.office365.com. You set it under System settings → SMTP → “Microsoft 365 mailbox”. → Set up OTP login

• The mailbox needs an address entered; it is the sender.
• For a shared mailbox the connected account needs “Send As” or “Send on Behalf”.
• While the mailbox sends the system mail, it cannot be deleted, disabled or switched to another protocol; the form then names the reason. Change the sending route in the system settings first.

Test connection

After saving an account, Test connection is available. The test reports success (optionally with a message count) or the specific cause of the error. For new, not-yet-saved accounts the test is disabled.

For Microsoft 365 accounts the test also names the reason and the next step:

• “Microsoft connection required” — the account is not connected, or the sign-in has expired or lacks mail access (e.g. after a password change or a changed policy). → Connect the account with Microsoft again.
• “Mailbox or folder not reachable” — wrong address or folder name, no full access to the shared mailbox, or the access is not effective yet (see above).

Export / Import

The account list can be exported as JSON (mail-accounts-export-<date>.json) and re-imported – with a preview and conflict handling (skip or overwrite existing accounts). Passwords are stored encrypted in the database and never shown in plain text.

Microsoft 365 accounts are exported without their connection — the connection belongs to the sign-in on this installation. After the import the account shows “Connection required”; one “Connect with Microsoft” and it is ready. The same applies after restoring a desktop backup on another computer: the test then reports “Microsoft connection required”.

Limits & notes

• Requires the Administrator role.
• Available in web and desktop mode.
• The actual mail sending is additionally enabled via System settings → Chat features. → System settings
• Microsoft 365 as an agent source: the agent reads new messages from where it left off. Messages that later land in the folder with an older received date (moved in from another folder or marked unread again) are not picked up any more.

Related

• Email mailboxes (feature)
• Import an email mailbox as a source
• Set up Microsoft SharePoint – app registration, consent, quick start
• Administration (overview)