The CloudRadial AutomationAI Microsoft Exchange Online extension automates Exchange Online administration, from releasing a quarantined message to tracing mail flow and managing mailbox settings. This article covers what the extension can do, the app registration, directory roles, and credentials it needs, how to use the same setup from workflow script steps, how its approval gate works, and the Exchange assistant agent that ships with it. It is for Admins and Owners.
- What the Extension Covers
- Creating the App Registration
- Assigning the Directory Roles
- Providing the Credentials to Your Runner
- Using It From Workflow Script Steps
- Reads and Approval-Gated Changes
- The Exchange Assistant Agent
- What the Extension Does Not Do
What the Extension Covers
The extension provides 31 tools across five areas:
| Area | What you can automate |
| Quarantine | List quarantined messages, inspect one, and release or delete it |
| Mailbox settings | Read and set auto-reply, forwarding, and mailbox permissions |
| Mail flow and tracking | Trace messages, read delivery detail, and enable or disable transport rules |
| Recipients and groups | Look up recipients and manage distribution group membership |
| Protection policy and allow/block | Read protection policies, and add or remove tenant allow/block list entries |
Install it from Extensions the same way as any other catalog extension. Adding a capability later is a catalog change rather than anything you install or configure on the runner.
Creating the App Registration
The extension authenticates to the Exchange admin API with an app-only (client-credentials) token, so it runs unattended with no signed-in user. Create a Microsoft Entra ID app registration for it in the tenant that hosts your mailboxes. That is not necessarily the tenant your Azure subscriptions live in; the two are frequently different directories.
- Register a new single-tenant application in the Microsoft Entra admin center. Give it a name you will recognize, such as
AutomationAI Exchange Online. No redirect URI is needed. A dedicated app is recommended over reusing your Microsoft 365 extension's app, so Exchange admin access stays separate from Microsoft Graph access. - Record the Application (client) ID and the Directory (tenant) ID from the app's Overview page.
- Under API permissions, select Add a permission > APIs my organization uses > Office 365 Exchange Online > Application permissions, add
Exchange.ManageAsApp, and then select Grant admin consent. This is the only API permission the extension needs; no Microsoft Graph permission is used. - Create a client secret under Certificates & secrets and copy its value before you leave the page. Microsoft shows it only once. A 12-month expiry is sensible; note the date and rotate the secret before it lapses.
One app registration and one set of credentials serve every capability listed above, because they all reach the same Exchange admin endpoint. The same app also serves any PowerShell, Python, or C# workflow step that calls Exchange Online, so one setup covers every way AutomationAI manages Exchange.
Choosing a Directory Role
For the full tool set, assign the app registration both of these Microsoft Entra directory roles. In the Microsoft Entra admin center, go to Roles & admins, select the role name, select Add assignments, and search for the app by its full name.
- Exchange Administrator covers mailboxes, forwarding, automatic replies, mailbox and send-as permissions, recipients, distribution groups, message trace, transport rules, connectors, anti-spam and anti-phishing policies, and the tenant allow/block list
- Security Administrator covers quarantine: listing messages, reading headers, releasing, deleting, and reporting a message to Microsoft as a false positive. Quarantine is governed by Microsoft Defender permissions rather than Exchange ones, so Exchange Administrator alone cannot act on it.
If your tenant uses Privileged Identity Management (PIM), make both assignments Active. An app cannot activate an eligible role.
If you want a smaller footprint, you can assign less:
- Quarantine only: Security Administrator alone
- Read-only: Global Reader alone. Every tool that makes a change then returns a permission error.
Do not use Global Administrator. Role assignments can take up to about 30 minutes to reach Exchange Online, so a 401 or 403 error straight after setup usually just means you need to wait. After that, a 401 or 403 means the app registration is missing a role, and the agent reports which role is missing rather than retrying.
Providing the Credentials to Your Runner
Store three secrets in your runner's Key Vault with these exact names:
| Secret | Value |
MicrosoftExchange-ClientId |
The Application (client) ID GUID |
MicrosoftExchange-TenantId |
Your Entra directory (tenant) ID GUID |
MicrosoftExchange-ClientSecret |
The client secret value |
Use the directory (tenant) ID of the tenant that hosts your mailboxes. For how to add these, see the article on updating secrets in your runner's Key Vault. The tenant ID is supplied to every call from the vault rather than from the automation itself, so an agent cannot direct a tool at a different tenant.
Using It From Workflow Script Steps
PowerShell, Python, and C# script steps can manage Exchange Online with the same app registration and the same three secrets. They read the secrets from your runner's Key Vault and make the same two calls the extension makes, so they need no extra module or permission:
- Get a token by sending
POST https://login.microsoftonline.com/{TenantId}/oauth2/v2.0/tokenwith the form fieldsgrant_type=client_credentials,client_id,client_secret, andscope=https://outlook.office365.com/.default. - Run a cmdlet by sending
POST https://outlook.office365.com/adminapi/beta/{TenantId}/InvokeCommandwith the headerAuthorization: Bearer <token>and a body such as{"CmdletInput":{"CmdletName":"Get-Mailbox","Parameters":{"Identity":"user@contoso.com"}}}. Results are returned invalue.
PowerShell steps that prefer the ExchangeOnlineManagement module (Connect-ExchangeOnline) must sign in with a certificate, because the module does not accept a client secret for app-only sign-in. Upload a certificate to the same app registration and add these optional, script-only secrets to your runner's Key Vault:
-
MicrosoftExchange-Organization, the tenant's.onmicrosoft.comdomain - Either
MicrosoftExchange-CertificateThumbprint, orMicrosoftExchange-Certificate(a base64-encoded PFX) together withMicrosoftExchange-CertificatePassword
The directory roles above apply unchanged. Agents and script steps combine freely; for example, a script step collects data, an agent judges it, and the change happens through an approval-gated tool. Script steps never pause for approval, so a script that makes changes must carry its own confirmation step.
Reads and Approval-Gated Changes
Of the 31 tools, 18 are read-only and run without interruption. The remaining 13 change something and are approval-gated: the run pauses and the request appears as an Action Required item in the Inbox until someone approves it. See the article on handling Action Required items in the Inbox.
Recipient scoping is enforced by Exchange itself rather than by how a request is worded, and the release-to-all option is fixed rather than something an automation can choose.
The Exchange Assistant Agent
The extension ships with an Exchange assistant agent you can install from the agent catalog and bind to an Agent node. It is set to preview changes by default, so it plans an action and shows you what it would do rather than acting immediately. A quarantine check-and-release workflow template is also available to import as a starting point.
What the Extension Does Not Do
Some operations are deliberately excluded because their blast radius is tenant-wide:
- Transport rules can be enabled and disabled, but not created or deleted
- Protection policies can be read, but not edited
- There is no general-purpose tool for running an arbitrary Exchange command
Some Microsoft 365 administration is also outside what this app registration can reach:
-
Security & Compliance PowerShell (
Connect-IPPSSession), used for content search and purge, retention, and data loss prevention, uses a different resource. It needsExchange.ManageAsAppon Microsoft Exchange Online Protection and the Compliance Administrator role, and Microsoft does not support app-only sign-in for eDiscovery cmdlets. -
Microsoft 365 Group membership (
Add-UnifiedGroupLinks,Remove-UnifiedGroupLinks,New-UnifiedGroup,Remove-UnifiedGroup) does not work with app-only access. Use the Microsoft 365 extension, which works through Microsoft Graph, for those.
If you are still having trouble, we're here to help! Submit a ticket for assistance, and don't forget to check our status page to ensure there are no outages in your area.
Comments
0 comments
Please sign in to leave a comment.