Email Setup
Set up the email infrastructure once, then connect a sending mailbox using either OAuth Sign-In or Exchange RBAC. Open Settings > General and expand the Email Notifications card.
On This Page
Pick a sending mode and connect a mailbox. Jump to a section below.
The email app registration is created during install
StratoLens uses a dedicated app registration for email sending, separate from the main authentication app. It's provisioned automatically when StratoLens is installed, no manual setup is required. Once the Mailbox Connection section appears in the card, you're ready to pick a sending mode below.
Choose one sending mode
OAuth Sign-In is faster to set up but requires re-authentication if the token expires or gets revoked. Exchange RBAC takes more steps but has no token expiration. Modes are mutually exclusive, switching modes replaces the existing configuration.
OAuth Sign-In Mode
Sign in as the sender mailbox account in a Microsoft popup to authorize StratoLens to send mail on its behalf. Faster setup, but the authorization can expire.
Link a mailbox
- On the OAuth Sign-In tab, click Link Mailbox. A Microsoft sign-in popup opens.
- Sign in as the mailbox account itself, not as your own admin account. This is the account StratoLens emails will be sent from.
- Approve the consent prompt. The popup closes automatically.
- The card now shows the linked mailbox, display name, link timestamp, and the admin who linked it.
Sign in as the mailbox, not yourself
The signed-in account becomes the sender for all StratoLens email. If you sign in as your own admin account, every notification will appear to come from you. Sign in as the dedicated shared mailbox or service account.
Token lifetime
OAuth authorization typically remains valid as long as emails send at least once every 90 days. Tenant-level events such as conditional access changes, password resets, or admin-revoked tokens can invalidate the authorization at any time. If that happens, unlink and re-link the mailbox.
Exchange RBAC Mode
Grant the email app application-level send permission scoped to a single mailbox using Exchange Online RBAC. More setup steps, but no token expiration.
Configure the mailbox
- Switch to the Exchange RBAC tab. Enter the sender mailbox address (placeholder:
stratolens-noreply@contoso.com). - Click Configure Mailbox. The PowerShell commands panel appears below, pre-filled with the correct client ID, service principal Object ID, and mailbox address.
- Open Exchange Online PowerShell (signed in as Exchange Administrator or Global Administrator).
- Run each command in order, using the per-command Copy button. Wait for each to succeed before running the next.
- Wait for propagation. Exchange RBAC changes typically take 30 minutes to 2 hours to take effect across the tenant.
Propagation delay is normal
Test emails sent during the 30-minute to 2-hour propagation window typically fail with a 403 error. This is expected. Wait it out and try again. The card shows a propagation delay banner during this window.
Scope is locked to one mailbox
The Exchange RBAC scope and role assignment are named with your customer name to prevent collisions when multiple StratoLens deployments share a tenant. The app cannot send mail from any other mailbox in the tenant.
List or remove the configuration
Click List / Remove Commands to open a dialog with two grouped sections of PowerShell commands: Verify Configuration (read-only checks) and Remove Configuration (cleans up the scope and role assignment).
Switching modes
Switching from one mode to the other replaces the existing configuration. The inactive tab shows a mode-switch info note when the other mode is currently configured.
Test Email
Once a mailbox is configured, the Test Email section appears. Enter a single recipient (placeholder: your-email@contoso.com) and click Send Test Email.
The result banner displays the success or failure message. On failure, mode-aware troubleshooting hints surface inline. The last test result also persists below the section as "Last test: Passed/Failed on <timestamp> to <recipient>".
Unlink the Mailbox
Use Unlink Mailbox to disable email sending or to switch modes. A confirmation dialog appears with mode-specific copy:
- OAuth
- Confirms the linked mailbox. Unlinking immediately revokes the stored authorization.
- Exchange RBAC
- Confirms the configured mailbox and notes that unlinking does not remove the Exchange RBAC permissions in Exchange Online. Use the List / Remove Commands dialog to clean those up manually.
Prerequisites
- StratoLens permissions
- Read Settings to view the section. Modify Settings to set up, link, unlink, configure, or send test emails.
- For Exchange RBAC
- Exchange Administrator or Global Administrator role to run the PowerShell commands.
- Sender mailbox
- A shared mailbox (recommended, no license required) or a regular user mailbox. For OAuth, the mailbox must have sign-in enabled with a password. For Exchange RBAC, sign-in does not need to be enabled.
Troubleshooting
Test email failed: insufficient permissions (Exchange RBAC mode)
Answer
Either the PowerShell commands haven't been run yet, or Exchange RBAC is still propagating, allow up to 2 hours. Open List / Remove Commands and run the verification commands in the Verify Configuration section to confirm the scope and role assignment exist.
Test email failed: token expired or re-link required (OAuth mode)
Answer
The OAuth authorization has been revoked or expired. Click Unlink Mailbox, then Link Mailbox again and sign in as the mailbox account.
Test email failed: mailbox not found
Answer
Confirm the shared mailbox exists in Exchange Online. For OAuth, also confirm sign-in is enabled with a password.
Sign-in popup didn't open
Answer
Your browser is blocking popups. Allow popups for the StratoLens hostname and try again.