The workspace mailbox is the address your customers write to and the address SAQ replies from. Once connected, incoming mail becomes tickets and comments, notifications go out as threaded replies, and timesheet documents are delivered from it. Owners and Admins connect it under Settings → Channels → Mailbox, whose intro states the requirement: "Connect the workspace mailbox. Microsoft 365 setup must prove access to this mailbox and denied access to a second mailbox."
Before you start
- You need the Owner or Admin role, and SAQ asks you to re-authenticate before saving credentials.
- One mailbox per workspace. Use a dedicated shared mailbox such as
support@acme.example, not a person's inbox. - For Microsoft 365 you need an administrator of the Microsoft tenant to register the application and scope its permissions. For IMAP / SMTP you need the server details and a mail server that writes a trusted
Authentication-Resultsheader. - The mailbox is available on every plan.
Fields
Choose the Provider and enter the Mailbox address. The remaining fields depend on the provider.
| Provider | Field | Meaning |
|---|---|---|
| Microsoft 365 | Tenant ID | The Entra tenant (directory) ID. |
| Microsoft 365 | Application ID | The application (client) ID of the app registration. |
| Microsoft 365 | Application secret | A client secret created on the app registration. Stored encrypted, never shown again. |
| Microsoft 365 | Second mailbox (must deny access) | Another real mailbox in the same tenant that the application must not be able to read. Used by the isolation test. |
| IMAP / SMTP | IMAP host, IMAP port (default 993), IMAP username, IMAP password, IMAP folder (default INBOX) |
Where SAQ reads mail. |
| IMAP / SMTP | SMTP connection URL | The connection URL of the server SAQ sends through, including its credentials. |
| IMAP / SMTP | Use implicit TLS | Ticked by default. |
| IMAP / SMTP | Trusted Authentication-Results service ID | The service ID your receiving mail server writes into Authentication-Results. Only results from this ID count as sender verification. |
Select Test isolation and connect.
What the isolation test proves
SAQ reads once from the mailbox you entered, which must succeed, and once from the Second mailbox, which must be refused (HTTP 403). A mailbox that does not exist (404) is not a pass, and the two addresses must differ. Passing proves that the application cannot read anyone else's mail in the tenant. If the test fails, nothing is saved and the page shows "Mailbox operation failed. Check credentials, recent authentication, and mailbox isolation."
Microsoft 365 setup
- In Microsoft Entra ID, register an application and create a client secret. Note the Tenant ID, the Application (client) ID, and the Object ID of the enterprise application (the service principal).
- Grant the application the application permissions
Mail.ReadWriteandMail.Send, and scope both to the workspace mailbox with Exchange Online application RBAC. Tenant-wide Entra mail permissions are additive, so do not leave any in place. Run in Exchange Online PowerShell, with your values:
Connect-ExchangeOnline
$saqAppId = '<application ID>'
$saqServicePrincipalId = '<enterprise application object ID>'
$saqMailbox = 'support@acme.example'
New-ServicePrincipal -AppId $saqAppId -ObjectId $saqServicePrincipalId -DisplayName 'SAQ'
New-ManagementScope -Name 'SAQ mailbox' -RecipientRestrictionFilter "PrimarySmtpAddress -eq '$saqMailbox'"
New-ManagementRoleAssignment -App $saqAppId -Role 'Application Mail.ReadWrite' -CustomResourceScope 'SAQ mailbox'
New-ManagementRoleAssignment -App $saqAppId -Role 'Application Mail.Send' -CustomResourceScope 'SAQ mailbox'
Test-ServicePrincipalAuthorization -Identity $saqAppId -Resource $saqMailbox
- In SAQ, choose Microsoft 365, enter the mailbox and the values above, another real mailbox in the tenant as Second mailbox, and select Test isolation and connect.
Tenants that already use an Exchange application access policy can keep it, as long as every grant is restricted to the one mailbox. Microsoft's guide: Application RBAC in Exchange Online.
Sender verification on Microsoft 365 uses Exchange Online's own DMARC result: a message is verified on dmarc=pass (or bestguesspass for a domain without a DMARC record) for the sender's domain. Unverified senders are quarantined; see Triage the Inbox.
IMAP and SMTP setup
Configure the receiving mail server to strip any Authentication-Results headers already present on incoming mail and to prepend its own with the DMARC result, and enter that server's service ID as the Trusted Authentication-Results service ID. An address alone never proves who sent a message; without a trusted result every sender is unverified and quarantined.
Health and polling
Once connected, the page shows the mailbox address, Connected or "The last mailbox operation failed; a retry is scheduled", and Last poll {date} (or "Not polled yet"). SAQ polls once a minute, so a message appears in the Inbox within about a minute. Messages larger than 25 MiB are not read. Automatic replies (out-of-office and similar) are dropped and never touch a ticket.
Replace the mailbox
Fill in the form with the new mailbox and select Replace the mailbox…, then type the current mailbox address and confirm Replace mailbox. The panel explains: "The current connection is discarded: its checkpoint, its backoff, and any send that has not left yet are retired, and polling starts over on the new mailbox. Mail already received stays. This cannot be undone."
Without a mailbox
- Invitations, login links, and password resets always come from SAQ's platform mailer, mailbox or not.
- Member notifications come from the platform mailer instead: subject and link, without the comment text and without threading. Replying to such an email does not reach the ticket.
- Customers and contacts are never mailed; shared comments reach them only through the workspace mailbox.
- Timesheet documents are produced and downloadable but not delivered; the Documents page shows "no mailbox".
See Email notifications.
Deliveries that need a decision
The page lists outgoing messages that failed or whose delivery is uncertain:
- "The provider refused this message before accepting it; it was not sent." Use Retry… to send it again, or Cancel delivery.
- "Delivery is uncertain; automatic resend is paused." The provider did not answer in time. Check the mailbox's Sent Items, then choose Mark accepted if it went out, Cancel delivery, or Retry… after acknowledging: "The provider may already have accepted this message. Retrying can send a duplicate. Confirm only after checking the mailbox."
Every decision asks you to Confirm ("Confirm the delivery resolution. This action is audited.") after a recent re-authentication. Marking a timesheet delivery as accepted also settles its billing run.
Messages that could not be processed lists incoming messages that SAQ could not turn into a ticket or comment: "Processing these messages failed repeatedly or hit an error the pipeline cannot resolve. Retrying puts a message back in the queue; the action is audited." Select Retry processing and Confirm.
Common problems
The isolation test fails although the credentials are right. The application can read the second mailbox, or the second mailbox does not exist. Check the Exchange RBAC scope, remove tenant-wide Mail.ReadWrite/Mail.Send grants, and pick an existing mailbox as the second one.
Health shows the retry message. A read or send failed; SAQ backs off and retries on its own. If it persists, check that the secret has not expired.
Senders are always unverified on IMAP. The service ID in the receiving server's Authentication-Results header does not match the one you entered, or the server does not write the header.