Initialize-EpsMailSender
Documentation out of date
The documentation below was written for a different copy of this script than the one published now. Read the script itself before you run it, or ask support@invardia.com.
- the .doc.json names no sha256 of the script it documents
- the .doc.json is for version 2.0.0, the published script is 2.0.107
The published script's own summary: Sets up Entra Policy Suite's mail (framework MAIL-1): a shared mailbox the engine sends its alerts from - and the right to send as THAT mailbox only.
Purpose
Creates (or uses) a shared mailbox and gives the engine's managed identity the right to send as that mailbox and no other (Exchange RBAC for applications), removes a tenant-wide Graph Mail.Send grant on the identity, and stores the mail settings in the Entra Policy Suite database.
When to run it
Once after the install, and again to change the sender or the recipients.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| entraRole | Exchange Administrator (and Global Administrator for the Graph grant check) | the tenant | creates the mailbox, the Exchange service principal, the scope and the role assignment |
| azureRbac | Contributor (or any role that may start a Container Apps job) | the install's resource group | starts the database setup job, which stores the mail settings (audited) - no database right needed (installs made since 2.0.59); an older install: the SQL server's Entra admin stores them directly |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Exchange Online | create | the shared mailbox (if it does not exist; no licence) | the tenant | the alerts are sent from it | Remove-Mailbox | |
| Exchange Online | create | service principal for the engine identity, management scope <sender>-SendScope | the tenant | Exchange RBAC for applications needs both | Remove-ManagementScope, Remove-ServicePrincipal | |
| Exchange Online | grant | the engine identity (id-eps-engine) | Application Mail.Send | the sender mailbox ONLY (the management scope) | it sends the alerts | Remove-ManagementRoleAssignment EPS-MailSend-<app id> |
| Entra | remove | a tenant-wide Graph Mail.Send app role on the engine identity, if present | Mail.Send | the tenant | it would let the engine send as any mailbox, beside the scope | not wanted |
| SQL | update | settings Mail.Mode, Mail.Sender, Mail.Recipients (Platform.EnvironmentName) | the Entra Policy Suite database | the engine reads them | set Mail.Mode to none |
What it only reads
- Exchange: the mailbox, the organization config, the service principals, scopes and role assignments
- Graph: the engine identity's app roles
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -TenantId | yes | your Entra tenant | |
| -SubscriptionId | yes | the subscription Entra Policy Suite is installed in | |
| -Sender | yes | the shared mailbox's address | |
| -Recipients | yes | who gets the alerts | |
| -ResourceGroup | no | rg-eps | the install's resource group (an install made before 2.0.55: rg-entrapolicysuite, found by itself when it is there) |
| -EnvironmentName | no | the environment's name in every mail (subject and footer) |
Preview with -WhatIf
Every step it would take and the settings it would store; nothing is changed.
Undo
Remove the role assignment, the scope, the Exchange service principal and (if created) the mailbox; set Mail.Mode to none.
Network
It connects to: login.microsoftonline.com, management.azure.com, graph.microsoft.com, outlook.office365.com, <server>.database.windows.net
Download and run
Run these lines in PowerShell: the first downloads the script into the current folder, the second runs it.
Invoke-WebRequest https://invardia.com/support/eps/Initialize-EpsMailSender.ps1 -OutFile Initialize-EpsMailSender.ps1
.\Initialize-EpsMailSender.ps1 -TenantId <TenantId> -SubscriptionId <SubscriptionId> -Sender <Sender> -Recipients <Recipients>To check the download first, compare its SHA-256 with the published one:
SHA-256 16338c80463d598a4cccf2ff04adcd18f3ab7f03cd407e6fd55fd75121993c5f
Checksums: SHA256SUMS.txt · Version 2.0.107 · Documentation for version 2.0.0
Before you run it, compare the file's SHA-256 with its line in SHA256SUMS.txt.
Every parameter: Get-Help .\Initialize-EpsMailSender.ps1 -Full · Source: Initialize-EpsMailSender.ps1
Every script, identity and permission for your security review: Entra Policy Suite