Windows Server - How to Send SMTP Auth E-Mail with PowerShell

A couple of years ago I published an article explaining how to send notification E-Mail messages with PowerShell. I wrote that post to demonstrate how a simple notification script could allow the Windows Event Viewer to send its warnings through e-mail messages even when the native "send to e-mail" feature was deprecated (such as in Windows Server 2012 and later).

Truth to be told, that little PowerShell script I wrote could also be used on a wider scenario - basically, every time you need to create custom messages and automate them using an internal relay service, such as:

The default SMTP server shipped with Windows Server.
A drop-in Windows porting to the Linux Sendmail, such as Fake Sendmail (or other similar alternatives).
A full-fledged SMTP service solution such as hMailServ, a neat open-source MTA / MHS service which I extensively reviewed a while ago.

All of the alternatives above can be properly configured to securely allow the relay of e-mail messages from the local machine to the WAN, either using unauthenticated (yet IP-restricted) access or relying to the internal Window authentication: this is an ideal scenario for the Send-MailMessage cmdlet that I used within the script to actually send the e-mail messages.

What if you don't have (or don't want to rely to) an internal relay service, thus needing to use an external SMTP service? In such scenario, you'll most likely need to send the SMTP authentication data to the external service, and maybe even add or configure some custom message headers as well. Unfortunately, the Send-MailMessage cmdlet comes with a fairly limited amount of features and doesn't allow that kind of stuff.

Luckily enough there are better alternatives that we can use to achieve such result: I'm talking about the System.Net.Mail.MailMessage and Net.Mail.SmtpClient. two powerful .NET Framework objects that we can invoke with PowerShell. I've successfully used these classes when I developed RunningLow, a free PowerShell script that checks for low disk space and send e-mail to System Administrators (also available on GitHub).

Here's how RunningLow sends its e-mail notifications through an external SMTP server:

# ------------------------------------------------------ 
# SMTP configuration: username, password, SSL and so on
# ------------------------------------------------------ 
$email_username = "username@yourdomain.com";
$email_password = "yourpassword";
$email_smtp_host = "smtp.yourdomain.com";
$email_smtp_port = 465;
$email_smtp_SSL = 1;
$email_from_address = "username@yourdomain.com";
$email_to_addressArray = @("to1@yourdomain.com", "to2@yourdomain.com");

# [...]

# ------------------------------------------------------ 
# E-Mail message configuration: from, to, subject, body
# ------------------------------------------------------ 
$message = new-object Net.Mail.MailMessage;
$message.From = $email_from_address;
foreach ($to in $email_to_addressArray) {
    $message.To.Add($to);
}
$message.Subject = "Subject goes here";
$message.Body = "Message body goes here";

# [...]

# ------------------------------------------------------ 
# Create SmtpClient object and send the e-mail message
# ------------------------------------------------------ 
$smtp = new-object Net.Mail.SmtpClient($email_smtp_host, $email_smtp_port);
$smtp.EnableSSL = $email_smtp_SSL;
$smtp.Credentials = New-Object System.Net.NetworkCredential($email_username, $email_password);
$smtp.send($message);
$message.Dispose();

# ------------------------------------------------------

# SMTP configuration: username, password, SSL and so on

# ------------------------------------------------------

$email_username = "[email protected]";

$email_password = "yourpassword";

$email_smtp_host = "smtp.yourdomain.com";

$email_smtp_port = 465;

$email_smtp_SSL = 1;

$email_from_address = "[email protected]";

$email_to_addressArray = @("[email protected]", "[email protected]");

# [...]

# ------------------------------------------------------

# E-Mail message configuration: from, to, subject, body

# ------------------------------------------------------

$message = new-object Net.Mail.MailMessage;

$message.From = $email_from_address;

foreach ($to in $email_to_addressArray) {

$message.To.Add($to);

}

$message.Subject = "Subject goes here";

$message.Body = "Message body goes here";

# [...]

# ------------------------------------------------------

# Create SmtpClient object and send the e-mail message

# ------------------------------------------------------

$smtp = new-object Net.Mail.SmtpClient($email_smtp_host, $email_smtp_port);

$smtp.EnableSSL = $email_smtp_SSL;

$smtp.Credentials = New-Object System.Net.NetworkCredential($email_username, $email_password);

$smtp.send($message);

$message.Dispose();

I stripped the RunningLow source code down to its SMTP-relevant parts. As we can see, the code is splitted into three parts:

the SMTP configuration, where we specify the various SMTP server connection and authentication parameters.
the E-Mail configuration, where we create the System.Net.Mail.MailMessage object and setup the e-mail message stuff: from/to addresses, subject, body, and so on.
the Sending phase, where we create the System.Net.Mail.SmtpClient object and actually send the e-mail message.

There are a lot of things that we can do with these classes. For example, here's a list of the various properties that we can use to configure our System.Net.Mail.MailMessage object:

As we can see, there are a lot of things that can be done by mixing PowerShell cmdlets and these features, such as: adding attachments, importing the message body content from an external file using Get-Content, and so on.

That's it, at least for now: for additional info regarding the System.Net.Mail namespace, I strongly suggest to read the MSDN official docs.