Automate the sending of VSTS Release Summary emails

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.

"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.

5 thoughts on “Automate the sending of VSTS Release Summary emails

  1. Thanks for this post! You saved us from manually triggering “Send Email”.

    I want to mention a little issue we had, it may save others time too!

    We are using a different version of TSVS, and running the script as-is did not work.

    So we need to make a very little change for one of the headers;

    this line:
    $accept = “*/*;api-version=3.2-preview.1;excludeUrls=true”

    into this:
    $accept = “*/*;api-version=3.1-preview.1;excludeUrls=true”

    And it works like a charm.

    So, you can detect your own api version and apply the change.

  2. Is there any documentation for this api? I’d like to customise a couple of settings but without documentation I’m flying blind.

  3. Thank you very much for this article ! It helps me a lot and with Developer Tools I was easily able to find all the informations !
    Just a side note : the “Accept” part of the header is different on my TFS installation (2017 on-premise).

  4. Can you please share other properties of requestBody as I could not find any documentation for this API, struggling to build request body with different options

Leave a Reply

Your email address will not be published.