Send email with PowerShell

Easily send your DevOps reporting by email with this PowerShell function, because the Send-MailMessage cmdlet is obsolete. Of course you’ll be using StartTLS and authenticated SMTP as additional security.

If you’re trying to send an email using the Send-MailMessage cmdlet, it throws a warning on your shell:

WARNING: The command ‘Send-MailMessage’ is obsolete. This cmdlet does not guarantee secure connections to SMTP servers. While there is no immediate replacement available in PowerShell, we recommend you do not use Send-MailMessage at this time. See https://aka.ms/SendMailMessage for more information.

Time for something else, right?

In this post I provide you with a small PowerShell function you can use as to send email over an secured SMTP connection with SMTP authentication and StartTLS. As a framework you can use it in your own scripting, extend it, and you can even turn it into a PowerShell module. The mail function is quite rudimentary and has a lot of assumptions in it. All provided AS-IS.

One-time donation

Your donation helps support me in the ongoing costs running a blog like this one. Costs like coffee ☕, web hosting services, article research, and so on. Thank you for your support❤️ https://www.paypal.com/paypalme/jreilink.

PowerShell function to send SMTP email

You can use the following function to send a basic email to an email address of your choosing. On your shell, or command line interface / cli, it prompts you for your SMTP authentication password. This way, using a SecureString, your password is not saved in PowerShells history file $env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine\ConsoleHost_history.txt.

Function Send-MyMailMessage($from, $to)
{
  $mailFrom = "${from}"
  $mailTo = "${to}"
  $Subject = "Test email"
  $Body = "This is my email message"
  $SMTPServer = "smtp.example.com"
  $SMTPClient = New-Object Net.Mail.SmtpClient($SMTPServer, 587)
  $SMTPClient.EnableSsl = $true
  $ww = read-host -AsSecureString "Provide your email password."
  $SMTPClient.Credentials = New-Object System.Net.NetworkCredential("${from}", "$(${ww} | convertfrom-securestring -AsPlainText)");
  $SMTPClient.Send($EmailFrom, $EmailTo, $Subject, $Body)
}

Be sure to change the SMTP server address on line 6, and maybe the SMTP port 587 on line 7.

When you call Send-MyMailMessage with arguments $from and $to, like:

PS > Send-MyMailMessage jan@example.com admin@example.net
Provide your email password.: *****************

and you fill out your SMTP authentication password, an email is sent to admin@example.net with jan@example.com as the sender’s from address.

Instead of using .NET’s SMTP Class Net.Mail.SmtpClient, you can also use and reference MailKit.

Such a small, and rather static, PowerShell mail sending function is ideal for DevOps reporting. Of course you can expand the function with additional input variables and command line arguments, etc.

Send-MgUserMail as Send-MailMessage replacement

Another great option is to switch to Send-MgUserMail as the Send-MailMessage replacement. Send-MgUserMail is located in the Microsoft.Graph.Users.Actions Module.

About Send-MgUserMail:

Send the message specified in the request body using either JSON or MIME format. When using JSON format, you can include a file attachment in the same sendMail action call. When using MIME format: This method saves the message in the Sent Items folder. Alternatively, create a draft message to send later. To learn more about the steps involved in the backend before a mail is delivered to recipients, see here.

It is not hard cooking up a Send-MgUserMail script to send an email. Harm Veenstra over at “PowerShell is fun :)” has detailed instructions setting this up. Check it out here:

• Using Send-MgUserMail as the Send-MailMessage replacement

Send-MailKitMessage

Send-MailKitMessage is also a replacement for the obsolete Send-MailMessage, implementing the Microsoft recommended MailKit library. I’ve written about using MailKit in .NET before on my Dutch blog ITFAQ.nl: SMTP e-mail versturen met .NET.

Installing Send-MailKitMessage module

Installing the Send-MailKitMessage module is as easy as:

Install-Module -Name "Send-MailKitMessage" -Scope CurrentUser # For current user only (does not require elevated privileges)

Install-Module -Name "Send-MailKitMessage" -Scope AllUsers # For all users (requires elevated privileges)

Send email using Send-MailKitMessage

Sending email using Send-MailKitMessage is easy and pretty straightforward. The aforementioned GitHub project page lists all parameters. As a test, I took some of them and created the following script:

using module Send-MailKitMessage;

#use secure connection if available ([bool], optional)
$UseSecureConnectionIfAvailable = $true;

#authentication ([System.Management.Automation.PSCredential], optional)
$SMTPUser = "emailaddress@example.org"
$SMTPPass = "your-p4ssw0rd%"
$Credential = [System.Management.Automation.PSCredential]::new("${SMTPUser}", (ConvertTo-SecureString -String "${SMTPPass}" -AsPlainText -Force));

#SMTP server ([string], required)
$SMTPServer = "smtp.example.org";

#port ([int], required)
$Port = 587;

#sender ([MimeKit.MailboxAddress] http://www.mimekit.net/docs/html/T_MimeKit_MailboxAddress.htm, required)
$From = [MimeKit.MailboxAddress]"sender@example.org";

#recipient list ([MimeKit.InternetAddressList] http://www.mimekit.net/docs/html/T_MimeKit_InternetAddressList.htm, required)
$RecipientList = [MimeKit.InternetAddressList]::new();
$RecipientList.Add([MimeKit.InternetAddress]"recipient@example.com");

#subject ([string], optional)
$Subject = [string]"Test email";

#text body ([string], optional)
$TextBody = [string]"TextBody";

#HTML body ([string], optional)
$HTMLBody = [string]"HTMLBody";

#splat parameters
$Parameters = @{
    "UseSecureConnectionIfAvailable" = $UseSecureConnectionIfAvailable    
    "Credential" = $Credential
    "SMTPServer" = $SMTPServer
    "Port" = $Port
    "From" = $From
    "RecipientList" = $RecipientList
    "Subject" = $Subject
    "TextBody" = $TextBody
    "HTMLBody" = $HTMLBody
};

#send message
Send-MailKitMessage @Parameters;

As you can see I changed $Credential a bit so not all is in one line and SMTP username and SMTP password are in their own variables. Be sure to set (and keep) $UseSecureConnectionIfAvailable to $true, as this sets MailKit.Security.SecureSocketOptions to Auto. Making the SMTP connection uses StartTLS / TLS if available on your SMTP server.

Frequently Asked Questions

Conclusion

This post showed you how to send email with PowerShell using Net.Mail.SmtpClient, because the PS Send-MailMessage cmdlet is obsolete. The provided function uses StartTLS for encryption and SMTP authentication to your SMTP server for additional security. As an alternative to Send-MailMessage, information about Send-MgUserMail and an example for Send-MailKitMessage are also provided.