Build a Nightly Azure VM Auto-Shutdown That Emails You When It’s Done — Part 1: The Automation Runbook

Straight talk: do this one in the portal. Domain verification is an interactive flow with DNS records you need to copy out and paste into your registrar, and scripting it buys you nothing on a one-time setup. This is the step where clicking genuinely wins.

It’s also the fiddliest part, mostly because it’s two resources that people assume are one.

• Create an Email Communication Service resource. This owns the sending domain.
• In it, add a domain. Two choices:
• Azure Managed Domain — one click, no DNS, gives you a sender like DoNotReply@a1b2c3d4.azurecomm.net. Rate-limited and unbranded, but working in five minutes. Perfect for getting this running today.
• Custom domain — somedomainsomewhere.com, requires TXT, SPF, and DKIM records at your DNS provider and a wait for verification. This is what you want in production.
• Create a separate Communication Service resource, acs-email-eng-test-eastus.
• In the Communication Service, go to Email → Domains → Connect domain and attach the domain from step 2. Miss this and every send fails with a domain-not-linked error that reads like a permissions problem. It isn’t.
• Copy the endpoint from Keys — something like https://acs-email-eng-test-eastus.unitedstates.communication.azure.com.

Now grant the Automation Account’s identity permission to send. Skip the connection string entirely — we’re using Entra ID.

Portal. Open the Communication Service → Access control (IAM) → Add role assignment → Communication and Email Service Owner → Managed identity → Automation Account → aa-vmops-eng-test-eastus.

PowerShell.

$acs = Get-AzResource -ResourceGroupName 'acs-eng-test-eastus-rg' `
    -Name 'acs-email-eng-test-eastus' `
    -ResourceType 'Microsoft.Communication/CommunicationServices'

New-AzRoleAssignment -ObjectId $principalId `
    -RoleDefinitionName 'Communication and Email Service Owner' `
    -Scope $acs.ResourceId

If that role is broader than you’d like, a custom role carrying just Microsoft.Communication/EmailServices/Send/action scoped to the ACS resource is the tighter option.

Step 5 — Runtime Environment and the Module Nobody Expects

Azure Automation runs runbooks inside Runtime Environments, and PowerShell 7.4 is only available through them.

Portal. Automation Account → Runtime Environments → Create. Name it pwsh74-vmops, set Language to PowerShell and Runtime version to 7.4. On the Packages tab you’ll see Az and Azure CLI already present.

Now the part that catches everyone. Az.Communication is not included. Click + Add from gallery, search Az.Communication, add it, and give it a few minutes to import.

Skip this and your runbook will pass its syntax check, run fine right up to the email step, and then fail with a command-not-found error at 12:00 AM. Nobody sees it until morning.

Command line. Runtime Environment management is portal-and-REST for now — there’s no first-class az automation runtime-environment command group yet. If you need this in a pipeline, deploy it with an ARM template against Microsoft.Automation/automationAccounts/runtimeEnvironments. For a one-time build, use the portal and move on.

Step 6 — The Runbook

Portal. Runbooks → Create a runbook. Name Stop-TaggedVMs, type PowerShell, runtime environment pwsh74-vmops. Paste the script below into the editor, then Save.

PowerShell. Save the script locally as Stop-TaggedVMs.ps1 and import it — much better if you keep runbooks in Git, which you should:

Import-AzAutomationRunbook -ResourceGroupName 'acs-eng-test-eastus-rg' `
    -AutomationAccountName 'aa-vmops-eng-test-eastus' `
    -Path '.\Stop-TaggedVMs.ps1' `
    -Type PowerShell -Name 'Stop-TaggedVMs' -Force

Here’s the runbook itself.

<#
.SYNOPSIS
    Deallocates Azure VMs carrying a specified tag and emails a summary.

.DESCRIPTION
    Intended to run as a scheduled Azure Automation runbook. Authenticates
    with the Automation Account's system-assigned managed identity, finds
    every VM matching the supplied tag, deallocates any that are running,
    and sends an HTML summary through Azure Communication Services.

    Deallocate is used rather than power off so that compute billing stops.

.PARAMETER ResourceGroupName
    Resource group to search. Omit to search the whole subscription.

.PARAMETER TagName
    Tag key identifying shutdown candidates. Default: AutoShutdown.

.PARAMETER TagValue
    Tag value identifying shutdown candidates. Default: True.

.PARAMETER RecipientAddress
    Email address receiving the summary.

.PARAMETER WhatIfOnly
    Report what would be stopped without stopping anything.

.NOTES
    Author  : John O'Neill Sr.
    Company : Azure Innovators
    Version : 1.0.0
    Requires: PowerShell 7.4 Runtime Environment
              Az.Accounts, Az.Compute, Az.Communication
    Prereqs : System-assigned managed identity with VM deallocate rights
              and Communication and Email Service Owner on the ACS resource.
#>

param(
    [string] $ResourceGroupName = 'acs-eng-test-eastus-rg',
    [string] $TagName           = 'AutoShutdown',
    [string] $TagValue          = 'True',
    [string] $RecipientAddress  = 'cloudops@somedomainsomewhere.com',
    [bool]   $WhatIfOnly        = $false
)

$ErrorActionPreference = 'Stop'

$acsEndpoint = 'https://acs-email-eng-test-eastus.unitedstates.communication.azure.com'
$senderAddress = 'DoNotReply@somedomainsomewhere.com'
$timeZoneId  = 'Eastern Standard Time'

$stopped = [System.Collections.Generic.List[string]]::new()
$skipped = [System.Collections.Generic.List[string]]::new()
$failed  = [System.Collections.Generic.List[string]]::new()

try {
    Write-Output 'Authenticating with managed identity.'
    Connect-AzAccount -Identity | Out-Null

    $vms = Get-AzVM -ResourceGroupName $ResourceGroupName -Status |
        Where-Object { $_.Tags[$TagName] -eq $TagValue }

    Write-Output "Found $($vms.Count) tagged VM(s)."

    foreach ($vm in $vms) {
        $power = ($vm.Statuses |
            Where-Object Code -like 'PowerState/*').Code

        if ($power -ne 'PowerState/running') {
            Write-Output "$($vm.Name): already $power, skipping."
            $skipped.Add($vm.Name)
            continue
        }

        if ($WhatIfOnly) {
            Write-Output "$($vm.Name): WHATIF - would deallocate."
            $stopped.Add("$($vm.Name) (simulated)")
            continue
        }

        try {
            Write-Output "$($vm.Name): deallocating."
            Stop-AzVM -ResourceGroupName $vm.ResourceGroupName `
                      -Name $vm.Name -Force | Out-Null
            $stopped.Add($vm.Name)
        }
        catch {
            Write-Warning "$($vm.Name): failed - $($_.Exception.Message)"
            $failed.Add("$($vm.Name): $($_.Exception.Message)")
        }
    }
}
catch {
    Write-Error "Fatal error before shutdown loop: $($_.Exception.Message)"
    throw
}

That’s the work. Now the report — and note that the timestamp is generated, never hardcoded. Change the schedule later and this email keeps telling the truth:

$runTime = [System.TimeZoneInfo]::ConvertTimeFromUtc(
    (Get-Date).ToUniversalTime(),
    [System.TimeZoneInfo]::FindSystemTimeZoneById($timeZoneId))

$stamp = $runTime.ToString('MMMM d, yyyy \a\t h:mm tt') + ' Eastern'

function Format-Section {
    param([string] $Heading, [System.Collections.Generic.List[string]] $Items)
    if ($Items.Count -eq 0) { return '' }
    $rows = ($Items | ForEach-Object { "<li>$_</li>" }) -join ''
    return "<h3>$Heading ($($Items.Count))</h3><ul>$rows</ul>"
}

$body  = "<p>Nightly VM shutdown completed at <strong>$stamp</strong>.</p>"
$body += Format-Section -Heading 'Deallocated'  -Items $stopped
$body += Format-Section -Heading 'Already off'  -Items $skipped
$body += Format-Section -Heading 'Failed'       -Items $failed
$body += "<p>Resource group: $ResourceGroupName</p>"

$status = if ($failed.Count -gt 0) { 'ATTENTION' } else { 'OK' }
$subject = "[$status] Nightly VM Shutdown - $($stopped.Count) deallocated"

$message = @{
    ContentSubject   = $subject
    ContentHtml      = $body
    ContentPlainText = "Shutdown completed at $stamp. " +
                       "Deallocated: $($stopped.Count). Failed: $($failed.Count)."
    SenderAddress    = $senderAddress
    RecipientTo      = @(@{ Address = $RecipientAddress; DisplayName = 'Cloud Ops' })
}

try {
    Send-AzEmailServicedataEmail -Message $message -Endpoint $acsEndpoint | Out-Null
    Write-Output 'Summary email queued.'
}
catch {
    Write-Error "Shutdown succeeded but email failed: $($_.Exception.Message)"
}

if ($failed.Count -gt 0) {
    throw "$($failed.Count) VM(s) failed to deallocate. See job output."
}

Two design decisions worth calling out. The email failure is caught but doesn’t re-throw — a broken mail relay shouldn’t make a successful shutdown look like a failed job. But a VM that wouldn’t stop does throw at the end, so the job shows as Failed in the portal and any alerting you’ve wired up actually fires.

Step 7 — Test Before You Schedule Anything