How to send an email using Powershell (Windows and cross-platform)

Powershell is a useful tool for scripting, automation, and software development. It can also send real emails without the need for a mail client or web browser. Using built in Send-MailMessage functionality we can send emails via SMTP in Powershell. In this post we will show you how in a few simple steps.

What is Powershell?

PowerShell is a command-line shell and programming language from Microsoft that first appeared in 2006 and is similar to Bash and cmd.exe. Powershell can be used for task automation and managing application and operating system configurations.

Why would you use Powershell to send emails?

Normally we send emails with a mail client like Outlook or Gmail but this process can be time consuming if we need to send many emails or automate a process. This is a great example of where Powershell can help us.

Send-MailMessage `
  -From welcome@mycompany.com `
  -To customer@app.com `
  -Subject 'Welcome'

Powershell newlines can be added to commands using the ` backtick character (as opposed to the \ backslash command to other environments).

Installing powershell

Powershell in scripting environment best known on Windows machines but is also available on Mac and Linux. This makes Powershell great for sending emails cross-platform.

Powershell on Windows

Powershell comes pre-installed on most Microsoft Windows runtimes. If not you can install it directly from the Microsoft website.

Powershell on Mac

Install Homebrew and then run:

brew install --cask powershell

Powershell for Linux

If you plan to use Powershell to send email on Ubuntu you can use apt-get to install the package:

sudo apt-get update
sudo apt-get install -y wget apt-transport-https software-properties-common
wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb"
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y powershell

Starting a shell session (quick refresher)

Once installed start the shell using pwsh in any terminal or clicking the Powershell icon in the windows start bar. Here is an example running th pwsh command on a Mac terminal. Notice the greeting and a new prompt starting with PS. We can now type commands that Powershell will execute.

me@MacBook-Air ~ % pwsh
PowerShell 7.2.5
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/Me>

Basic commands

Powershell is a scripting environment that means you type commands, hit enter, and the shell will print results on the next line. So for instance to see the current directory that the shell is operating in execute the Pwd command.

PS /Users/Me> Pwd

Path
----
/Users/Me

Notice how the result is printed under a Path property. That is because, unlike text-based Unix shells, Powershell is object based. We can manipulate the output of commands in an object-oriented way which can be quite powerful. We can even store variables in our script for later use.

Accessing objects and variables

Powershell returns objects from commands that we can chain together and manipulate in many ways. We will use these techniques later when sending emails. Let's see how command outputs can be controlled. Using the pipe operator | we can send the results of the preceding command to the command that follows. By passing the Pwd result to Get-Member we can see the properties available and the object type name. Here we see it is a PathInfo object with a Path string property available.

PS /Users/Me> Pwd | Get-Member

   TypeName: System.Management.Automation.PathInfo

Name         MemberType Definition
----         ---------- ----------
Path         Property   string Path {get;}

Let us run the same Pwd command but access the Path property.

PS /Users/Me> $string = (Pwd).Path
PS /Users/Me> echo $string
/Users/Me

To demonstrate the flexibility of variables we can reverse the string and print the path backwards.

PS /Users/Me> $string[-1..-$string.Length] -join ''
eM/sresU/

Saving scripts and executing files

When you want to run a complicated set of instructions it is best to write them into a file line by line and save it as a powershell script with the .ps1 extension. You can then invoke the script using the ./ prefix. For instance if you have a script.ps1 run it from Powershell with the command ./script.ps1.

Send-MailMessage command

To send emails the simplest way is to use the Send-MailMessage command. The method documentation looks like this:

Send-MailMessage
    [-Attachments <String[]>]
    [-Bcc <String[]>]
    [[-Body] <String>]
    [-BodyAsHtml]
    [-Encoding <Encoding>]
    [-Cc <String[]>]
    [-DeliveryNotificationOption <DeliveryNotificationOptions>]
    -From <String>
    [[-SmtpServer] <String>]
    [-Priority <MailPriority>]
    [-ReplyTo <String[]>]
    [[-Subject] <String>]
    [-To] <String[]>
    [-Credential <PSCredential>]
    [-UseSsl]
    [-Port <Int32>]
    [<CommonParameters>]

Each bracket contains an argument that can be passed to the command. To use the command to send email in Powershell we must first obtain access to an SMTP mailserver. The SMTP server will receive our mail send request and send the email to the desired destination using the SMTP protocol. Normal mail clients tend to use IMAP and POP3 but pretty much ever server will support SMTP so check with your provider.

Configuring SMTP access

Powershell reads a variable for SMTP access when you send emails called $PSEmailServer. Set this value before sending like so:

$PSEmailServer = 'my.smtp.server.com'

Or by passing arguments to the send command:

Send-MailMessage -SmtpServer 'my.smtp.server.com' -Port 587

Composing emails with Powershell

To send an email with Powershell include your destination recipients and a message body. A simple message might look like this:

Send-MailMessage -To my@dog.com -Subject '🐕 Walk time!' -From 'hu@man.com'

Send attachments with Powershell

You can read files with Powershell and attach them to your email by creating a new object System.Net.Mail.Attachment with the file path. Here is an example script showing how to include files in your email.

$To = "hello@mum.com"
$Sender = "good@son.com"
$Subject = "Happy mothers' day"
$Body = "Hi Mum. You are the best"
$SMTPServer = "mx.mailslurp.com"
$filenameAndPath = "C:\Users\Me\MumAndMe.png"
$SMTPMessage = New-Object System.Net.Mail.MailMessage($Sender,$To,$Subject,$Body)
$attachment = New-Object System.Net.Mail.Attachment($filenameAndPath)
$SMTPMessage.Attachments.Add($attachment)
$SMTPClient = New-Object Net.Mail.SmtpClient($SMTPServer, 587)
$SMTPClient.Credentials = New-Object System.Net.NetworkCredential($cred.UserName, $cred.Password);
$SMTPClient.Send($SMTPMessage)

When not to use Powershell (security concerns)

Powershell is great but has some drawbacks when sending emails. According to Microsoft the Send-MailMessage is obsolete and no longer recommended as it cannot guarantee secure connections. For that reason it is important to consider some alternatives such as the free Powershell package MailSlurp. Running Send-MailMessage confirms this by printing the warning below:

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.

Alternative methods for sending email in Powershell

A great way to send emails in Powershell without using the Send-MailMessage command is by using a free and secure email API service like MailSlurp. MailSlurp offers SMTP mail servers with custom API access so you can send and receive emails in any scripting environment using secure connections. The first step is to sign up and obtain a free API Key.

Then create a new inbox email address to send emails with. Save the inbox ID as this is important for the next step:

Send email using Invoke-WebRequest

To send an email using MailSlurp simply make an HTTP/S POST request and pass the message parameters as JSON:

# set API_KEY env variable to MailSlurp API Key
$apiKey = $Env:API_KEY
Write-Output "Running send script with key $apiKey"

# get inbox to send with
$inboxes = Invoke-WebRequest -Uri "https://api.mailslurp.com/inboxes" -Headers @{"x-api-key"=$apiKey;} | ConvertFrom-Json
$email = $inboxes[0].emailAddress
$inboxId = $inboxes[0].id

# Send the email
$params = @{
 "to"=@($email);
 "subject"="Testing 123";
 "body"="Hello";
}
$status = Invoke-WebRequest `
	-Uri "https://api.mailslurp.com/inboxes/$inboxId" `
	-Method POST `
	-Body ($params|ConvertTo-Json) `
	-ContentType "application/json" `
	-Headers @{"x-api-key"=$apiKey;} | Select-Object -Expand StatusCode

Write-Output "Email sent with status $status"

Running the script returns a 201 status code if successful.

PS /Users/Me> ./send.ps1

StatusCode        : 201

Conclusion and next steps

Powershell is a great way to automate tasks including the sending of emails and attachments. Use the Send-MailMessage command to send emails and attachments using your own SMTP server. If you don't have one or need a more secure solution use an email API service like MailSlurp and the Invoke-WebRequest method to send your payload.

To take your scripting to the next level consider using the official MailSlurp library package on Nuget to write email automation in CSharp and F# instead.

Happy scripting!