Microsoft 365 Email

Available in the 0.22.0-rc.1 staging preview. Validate sending and intake against your own mailbox before enabling it for a school.

This connector sends through Microsoft Graph and imports new Inbox messages into the built-in ticket system. It uses a dedicated app credential, not a mailbox password. SMTP AUTH and basic authentication are not required.

Scope the app to the support mailbox

1. Provision an Exchange Online mailbox. A licensed user mailbox or a suitably provisioned shared mailbox may be used. Keep administrator recovery mail in another mailbox.
2. Register a dedicated single-tenant Entra application. Create a credential with a deliberate expiry and retain the tenant ID, client ID and secret value for secure connector setup. Do not put the secret in chat, source or logs.
3. Use Exchange Online RBAC for Applications to grant only Application Mail.Read and Application Mail.Send, with a management scope selecting this mailbox. The service principal Object ID comes from Enterprise Applications, not the app registration Object ID.
4. Do not also grant tenant-wide Graph Mail.Read or Mail.Send application permissions in Entra. Those grants are additive and would bypass the mailbox restriction. No Mail.ReadWrite, directory write or Exchange administration permission is needed by the running connector.

Example for an Exchange administrator, after connecting with Connect-ExchangeOnline. Substitute verified IDs and the exact mailbox before running. The commands create narrowly named resources; check for existing ones before repeating them.

New-ServicePrincipal -AppId '<client-id>' -ObjectId '<enterprise-service-principal-id>' -DisplayName 'Plugboard support email'
New-ManagementScope -Name 'Plugboard support mailbox' -RecipientRestrictionFilter "PrimarySmtpAddress -eq '[email protected]'"
New-ManagementRoleAssignment -Name 'Plugboard support read' -App '<enterprise-service-principal-id>' -Role 'Application Mail.Read' -CustomResourceScope 'Plugboard support mailbox'
New-ManagementRoleAssignment -Name 'Plugboard support send' -App '<enterprise-service-principal-id>' -Role 'Application Mail.Send' -CustomResourceScope 'Plugboard support mailbox'
Test-ServicePrincipalAuthorization -Identity '<enterprise-service-principal-id>' -Resource '[email protected]'
Test-ServicePrincipalAuthorization -Identity '<enterprise-service-principal-id>' -Resource '[email protected]'

The positive result must be in scope and the unrelated mailbox out of scope. Also verify with real Graph requests: the Exchange test does not include Entra grants. Permission cache propagation can take time. Never broaden the scope to make a connection test pass.

Configure Plugboard

Shared mailboxes use the same connector. Enter the shared mailbox’s primary SMTP address and scope the app’s Exchange roles to that mailbox. No shared mailbox password, interactive mailbox sign-in, or human delegate account is needed by this app-only connection. Test both incoming messages and sending as the shared mailbox; a successful connection check verifies only reading.

• Add Microsoft 365 Email under Admin > Connectors, using whole-organisation coverage and platform execution. Enter the tenant ID, client ID, exact mailbox and client secret. The platform seals the secret in its existing vault.
• Save and test. This checks mailbox read access. It does not send a message and cannot certify Mail.Send or final delivery.
• Select it as the default for sending email if another EMAIL connector is enabled. All current email delivery workflows use the existing email.send contract; ticket replies retain their MIME threading headers.
• Set the same mailbox address under Admin > Messages > Ticket mailbox. Enable plus addressing only after testing it on this mailbox.
• Enable Import new inbox messages as tickets and enable the connector. The worker checks once per minute. It imports messages received since this connector was created; old Inbox contents are not imported. Repointing the connector to another app or mailbox starts a fresh intake boundary.

Delivery and recovery

Graph HTTP 202 means Microsoft accepted a send for processing, not that the recipient received it. A send is not automatically repeated after an ambiguous transport failure, avoiding duplicate customer messages. Check Sent Items and recipient delivery before resending.

Intake does not mark, move or delete messages. It uses immutable Graph IDs, durable delta positions, and tenant-specific database locks. Each message and attachment has database-enforced replay protection. The page position advances only after message and attachment persistence succeeds. An expired delta token rebuilds the baseline with the original start time and replay protection.

One page (normally 25 changes) is handled per mailbox per scheduled run. File attachments are supported up to 20 files and 8 MB total per message. Item/cloud attachments and larger messages stop that page for operator attention rather than silently losing files. Investigate the source message and move it out of the Inbox only after retaining it through an appropriate alternative workflow. Messages moved out of the Inbox before polling are outside this intake scope.

The connector list shows paused, waiting, running, failed and overdue intake states. Disabling intake retains its position for later resumption. Turning off ticketing/integrations or putting the tenant into read-only mode stops scheduled ingestion. Mail body text stays in the ticket pipeline; it is not a connector log or assistant mailbox-reading tool.

Acceptance checks

Test a new request, a threaded reply, an attachment and a repeated page. Confirm one ticket/comment/file after replay. Test invalid credentials, an unscoped mailbox denial, disabled intake, worker restart, expired continuation and an attachment persistence failure. Verify public replies arrive and internal notes send nothing. Record real provider results separately from fixture tests.

References: Exchange application RBAC, Graph sendMail, Graph message delta.