Email notification step

Deployments can have a strong impact on the people whose work depends on the system being deployed. Great communication is an important part of a great deployment strategy, and email steps are a key way that Octopus can help you keep everyone in the loop. You may want to:

  • Notify stakeholders when a new version of an app has been deployed to production.
  • Let testers know when a new version is available in UAT.
  • Use email in conjunction with manual interventions approvals to make sure everyone is ready for a new deployment.

Getting Started - Email Notifications

Before you can add email steps to your deployment processes, you need to add your SMTP configuration.

SMTP configuration

To add your SMTP configuration navigate to Configuration ➜ SMTP and set the following values:

SMTP HostThe DNS hostname for your SMTP
SMTP PortThe TCP port for your SMTP server.25
TimeoutThe timeout for SMTP operations. Value is in milliseconds.12000 (12 seconds)
Use SSL/TLSThis option controls whether or not Octopus enforces using an SSL/TLS-wrapped connection.True
From AddressThe address which all emails will be sent ‘From’
CredentialsOptional SMTP login / password if your SMTP server requires / SuperSecretPa$$word

Click SAVE AND TEST to save the SMTP configuration and verify the values are valid:

You will be prompted for an email address to send a test email to:

Enter a test email address and click OK. A Send test email task will start to verify your SMTP Configuration:

Add an email step

Email steps are added to deployment processes in the same way as other steps.

  1. Navigate to your project’s overview page by selecting Projects and clicking on the project you are working with.

  2. Click PROCESS and ADD STEP to add a step to an existing process. Alternatively, if this is a new deployment process, click the DEFINE YOUR DEPLOYMENT PROCESS button, and click ADD STEP.

  3. Find the Send Email step, hover over the step, and click ADD.

  4. Give the step a short memorable name.

  5. The step will run on the Octopus Server.

  6. Choose the recipients of the email. You have several options:

    • Enter a comma-separated list of email addresses.
    • Bind to a variable which defines a list of email addresses (this is really useful for tailoring your recipient list per-environment).
    • Choose one or more teams to include members of those teams in the recipient list.
    • Use a combination of all of these options.

Octopus will build the resulting recipient list during the deployment, remove duplicate emails addresses, and send the email to each recipient. docs

  1. Provide a subject line for the emails. The subject can contain Octopus basic variable syntax.

  2. Add the body of the email. The email can be sent in plain text or HTML, and you can use Octopus extended variable syntax to include information about the deployment in the email. See the Email Template Examples below.

  3. You can set conditions to determine when the step should run. For instance:

    • Send the email only for successful deployments to certain environments.
    • Send a specific email for failed deployments.
    • Send an email based on the value of a variable expression which works really well with output variables.
  4. Save the step.

Email template examples

You can set the email subject and author the email body as plain text or HTML content. You can even use the Octopus variable syntax to include information about the deployment in the email.

Deployment summary template

This template collects basic information about the deployment, including the package versions included in each step.

<h1>Deployment of #{Octopus.Project.Name} #{Octopus.Release.Number} to #{Octopus.Environment.Name}</h1>
  <em>Initiated by
    #{unless Octopus.Deployment.CreatedBy.DisplayName}#{Octopus.Deployment.CreatedBy.Username}#{/unless}
    #{if Octopus.Deployment.CreatedBy.DisplayName}#{Octopus.Deployment.CreatedBy.DisplayName}#{/if}
    #{if Octopus.Deployment.CreatedBy.EmailAddress} (<a href="mailto: #{Octopus.Deployment.CreatedBy.EmailAddress}">#{Octopus.Deployment.CreatedBy.EmailAddress}</a>)#{/if}
    at #{Octopus.Deployment.Created}</em>
#{if Octopus.Release.Notes}
<h2>Release notes</h2>
<h2>Deployment process</h2>
<p>The deployment included the following actions:</p>
  #{each action in Octopus.Action}
    <li><strong>#{action.Name}</strong> #{if action.Package.NuGetPackageId}&mdash; <a href="{action.Package.NuGetPackageId}">#{action.Package.NuGetPackageId}</a> <em>version #{action.Package.NuGetPackageVersion}#{/if}</em></li>
<p>View the <a href="http://my-octopus#{Octopus.Web.DeploymentLink}">detailed deployment log</a>.</p>

To use the template in your projects, replace with the DNS name of your NuGet server, and my-octopus with the DNS name of your Octopus Server. Make sure you select Body is HTML on the email step configuration page.

The output of the template will be an HTML email like:

Including step status

The outcome of each step can be included using a template like the one below:

Step status summary template

<h3>Task summary</h3>
#{each step in Octopus.Step}
  #{if step.Status.Code}
    <li>#{step | HtmlEscape} &mdash; <strong>#{step.Status.Code}</strong>
    #{if step.Status.Error}
      <pre>#{step.Status.Error | HtmlEscape}</pre>
      <pre>#{step.Status.ErrorDetail | HtmlEscape}</pre>

Step error detail step.Status.Error and step.Status.ErrorDetail will only display the exit code and Octopus stack trace for the error. As we cannot parse the deployment log, we can only extract the exit/error codes. It cannot show detailed information on what caused the error. For full information on what happened when the deployment fails, you will need to reference the logs.

See System variables

Referencing package metadata

This example displays package ID and version numbers for any steps that reference a package.

#{each action in Octopus.Action}
  #{if Octopus.Action[#{action.StepName}].Package.PackageId}
    <b>PackageId: #{Octopus.Action[#{action.StepName}].Package.PackageId}</b>
    <b>Package Version: #{Octopus.Action[#{action.StepName}].Package.PackageVersion}</b>

Iterating over Octopus.Action like this above is a useful way to retrieve data from all steps in your process without having to refer to a hard coded step name that could potentially change.

Referencing additional package metadata

Using custom scripts you can include additional reference packages. This example displays package ID and version numbers for any steps that include additional reference packages.

#{each action in Octopus.Action}
  #{each package in action.Package}
    #{if Octopus.Action[#{action.StepName}].Package[#{package}].PackageId}
      <b>PackageId: #{Octopus.Action[#{action.StepName}].Package[#{package}].PackageId}</b>
      <b>Package Version: #{Octopus.Action[#{action.StepName}].Package[#{package}].PackageVersion}</b>

Iterating over both Octopus.Action and action.Package like this above is a useful way to retrieve data from all steps in your process without having to refer to a hard coded step or package reference name that could potentially change over time.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023