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. If you re-authenticate by signing in again through single sign-on, the page returns with the connection fields as you entered them, but without the credentials, which are never kept between pages: "You are signed in again. Enter the mailbox credentials once more and connect the mailbox." Every other action on this page (retention, purge, delivery decisions) is completed when the page returns.
- 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, as the text under the field explains. |
| 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. |
| Both | Credential expires | Optional. The date the provider shows for the application secret or the password. With it the owners are emailed 30 days, 7 days, and 1 day before, and the page shows the date. See When the credential expires. |
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; on the app registration's overview page, follow "Managed application in local directory"). Do not grant the application any API permissions in Entra: a tenant-wide
Mail.ReadWriteorMail.Sendapplication permission is additive and would let the application read every mailbox, so remove any that exist. - Grant the application access to the workspace mailbox, and to nothing else, with Exchange Online application RBAC. 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
The last command should list both roles with InScope set to True. Run it once more with the address you will enter as Second mailbox: that mailbox must not be in scope.
- 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.
If New-ManagementRoleAssignment is refused
The message "You don't have access to create, change, or remove the … management role assignment. You must be assigned a delegating role assignment to the management role" is about the signed-in administrator, not about the application. It does not mean that the application needs permissions in Entra. Three things have to be true, and each of them takes time to propagate in Exchange Online, from minutes to a few hours:
- The tenant has organization customization enabled. This is a one-time step in a tenant that has never changed its Exchange RBAC configuration: run
Enable-OrganizationCustomization, then wait. - The administrator holds the Role Management role. The Organization Management role group carries it. Membership that only comes from the Entra Global Administrator role is not always honoured for this command; add the account as a direct member with
Add-RoleGroupMember 'Organization Management' -Member '<admin address>' -BypassSecurityGroupManagerCheck(or from the Exchange admin center under Roles → Admin roles), then start a new session withDisconnect-ExchangeOnlineandConnect-ExchangeOnline. - The application, scope, and role exist.
Get-ServicePrincipal -Identity $saqAppId,Get-ManagementScope 'SAQ mailbox', andGet-ManagementRoleAssignment -Role 'Application Mail.ReadWrite' -Delegating $trueeach return a row.
When all three are in place and the command still fails, wait and reconnect before changing anything else. On Linux or macOS, Connect-ExchangeOnline -Device signs in with a code you enter in any browser.
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.
When the credential expires
A Microsoft 365 application secret is issued with an expiry (Entra allows at most 24 months), and some IMAP providers rotate passwords. Once the credential stops working, nothing is received or sent through the mailbox until a new one is saved. Record the date under Credential expires when you connect the mailbox. The page then shows "The mailbox credential expires {date}." (as a warning inside the last 30 days, and "The mailbox credential expired {date}." once it has passed), and the workspace owners receive an email 30 days, 7 days, and 1 day before the date: "The mailbox credential for {workspace} expires in {count} days". The email comes from SAQ's platform mailer, not from the workspace mailbox, so it arrives even when the mailbox has already stopped working. Each reminder is sent once; replacing the mailbox or correcting the date starts the reminders over.
To correct the date alone, change Expiry date of the current credential under Mailbox storage and select Save the date after a recent re-authentication: the connection is kept as it is. An empty date turns the reminders off. A partly typed date is refused: "Enter a complete date, or leave the field empty to keep the stored date unchanged."
To renew: create a new secret or password at the provider, then replace the mailbox with the same mailbox address, the new credential, and its new expiry date. Do this before the old credential expires.
Mailbox storage
SAQ reads the mailbox and never removes anything from it on its own. Every message it has read stays where it was, and on Microsoft 365 Exchange files a copy of every reply SAQ sends in Sent Items, so a busy mailbox grows on both sides. With IMAP/SMTP no copy of sent mail is filed. What SAQ keeps is the ticket: the comment, its attachments, and the original message source for 90 days. After that, the mailbox holds the only original copy.
Mailbox storage on the Settings → Mailbox page puts the two side by side. Select Check the mailbox (later Check again) and SAQ reads the live counts from the provider; the mailbox is read when you ask, not on every poll.
| Where | What it means |
|---|---|
| Inbox folder in the mailbox | Messages and size of the folder SAQ reads. |
| Sent Items in the mailbox | Messages and size of Sent Items on Microsoft 365. IMAP shows "Not kept: SMTP files no copy of what SAQ sends". |
| Received by SAQ | Messages SAQ has read from this mailbox. |
| Sent by SAQ | Replies and documents SAQ has sent from it. |
| Original copies SAQ still holds (90 days) | Received messages whose original source is still within the 90-day window. |
Size shows "Unknown" when the mail server does not report folder sizes.
Delete held mail from the mailbox
Only an Owner can have SAQ delete from the mailbox, and only mail SAQ already holds: messages it has received and, on Microsoft 365, the Sent Items copies of replies it sent. Mail from before the connection, mail a person sent by hand from the shared mailbox, and messages SAQ refused for size are never touched. The periods offered are 90, 180, and 365 days, never less, so the mailbox copy always outlives SAQ's own 90-day original.
Retention
Under Delete from the mailbox after, choose Never (keep the mailbox as it is) or a period and select Save after a recent re-authentication. The page explains: "Once a day, SAQ deletes from the mailbox the messages it has received and the replies it has sent that are older than this. Mail from before the connection, mail sent by hand, and messages SAQ refused for size stay. SAQ keeps the ticket content, and the original copy for 90 days."
The pass runs with the poll, once a day, and continues on the following polls until nothing older than the period is left. The page shows Last pass {date} once a pass has finished, or "The first pass runs with the next poll." Changing the period starts the clock again.
Purge now
Under Purge now: delete held mail older than, choose a period and select Purge the mailbox…. Type the mailbox address and confirm Delete from the mailbox after a recent re-authentication. The panel explains: "Messages older than {days} days that SAQ has received, and copies of replies SAQ has sent, are deleted from the mailbox. Nothing else in the mailbox is touched. After 90 days SAQ no longer holds the original copy, only the ticket content. This cannot be undone."
The purge runs in passes of up to 200 items per folder and keeps going until the period is empty, showing "Deleted {n} received messages and {n} sent copies from the mailbox." as it goes. On Microsoft 365 a pass looks at up to 2,000 of the oldest messages in a folder; when none of them is SAQ's, the purge stops there and adds "Older messages that SAQ never received were skipped; some may remain."
Deletion never disturbs polling: what SAQ has already read is not read again, and a message that arrives during a purge is picked up by the next poll.
Every retention change, every automatic pass that deleted something, and every purge is recorded in the audit log with the period and the counts, never the content.
Replace the mailbox
Once a mailbox is connected, the page shows it under Connected mailbox with its provider, and the connection form is hidden: "Mail is received and sent through this mailbox. To use another one, replace it: the current connection stays until the new mailbox has passed its test." Select Replace the mailbox… to open the form, fill in the new mailbox and its credentials, and select Continue to confirmation (or Cancel to keep the current mailbox). Then type the current mailbox address and confirm Replace mailbox. The panel explains: "SAQ tests the new mailbox first (on Microsoft 365 including the isolation test); nothing changes if the test fails. When it passes, 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 Timesheets 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 credential has not expired; the page shows the recorded expiry date, and replacing the mailbox with a new credential clears it.
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.