Automate the sending of VSTS Release Summary emails

Posted on Posted in VSTS

Release Summary emails are a great way to share details about a release, including which environments with status, related work items, and related bugs. While viewing a release’s details, click on the Send Email button to send out a Release Summary.

No option exists in VSTS (yet) to automatically send a Release Summary email, so we’ll use a quick PowerShell script to make the same API call that the VSTS web app makes. After sending a Release Summary email that is close to what we need and capturing the request body in Developer Tools, we use the following script to call the API.

$uri = $env:SYSTEM_TEAMFOUNDATIONSERVERURI + $env:SYSTEM_TEAMPROJECT + "/_apis/Release/sendmail/" + $env:RELEASE_RELEASEID
"Sending Release Email at " + $uri

$requestBody = "{""senderType"":1,""to"":{""tfsIds"":[""abcd1c6e-5a10-4d63-8a1f-abcd54c50704""],""emailAddresses"":[]},""subject"":""Automated Release Summary / Release-34 summary"",""cc"":{""tfsids"":[""efgh1c6e-5a10-4d63-8a1f-abcd54c50704""]},""sections"":[5,0,1,2,4]}"

$accessToken = $env:SYSTEM_ACCESSTOKEN
$auth = "Bearer $accessToken"
$accept = "*/*;api-version=3.2-preview.1;excludeUrls=true"
$headers = @{authorization=$auth;accept=$accept}

$contentType = "application/json"

Invoke-RestMethod -Uri $uri -Body $requestBody -Method Post -Headers $headers -ContentType $contentType

A few things to note

  • The script is making a web request and needs some way to authenticate with VSTS. We use the $env:SYSTEM_ACCESSTOKEN environment variable to get the OAuth token from Release Management. We need to tell the build agent to provide us with the OAuth token for this environment variable to be populated.
  • The request body requires valid VSTS users referenced by their tfsIds. You can easily capture the correct payload by performing a Send Release Summary in VSTS while running Developer Tools. While emailAddresses is a property of to, it has been ignored in all of my tests and only tfsIds get picked up.
  • Because this script is being run during the release, the summary email will show the environment as IN PROGRESS even if it is run as the last step in the Release. I’ve yet to find a better solution to this until VSTS offers the option to automate the email.
  • This is brittle. I could find no documentation of this API. We’re using the 3.2-preview.1 API which could change or be removed. Do not be surprised if this breaks with a future update.

With this script plugged into a PowerShell build step task, we can now trigger Release Summary emails whenever we desire.

Leave a Reply

Your email address will not be published. Required fields are marked *