Scripting – Test-SmtpConnection Powershell Module Released – Version 1.0

Griffon

Hello World,

In our previous post (Powershell Script Alternative to Telnet SMTP Connection test”),  we have quickly shared a small PowerShell Script that can be used to mimic the Telnet SMTP test against Exchange (or mail relay) server.   Surprisingly, the script  has proven to be quite popular around us.  Based on this modest success and in order to further improve the usage, we have decided to create a really simple PowerShell Script Module. 

The PowerShell Module will simplify the usage of the script and will basically make available the PowerShell Cmdlet that could be used to perform a basic Telnet SMTP Test connection. Based on the success of this Module, we might want to publish it on PowerShell Gallery….

So, let’s us introduce you our simple Test-SmtpConnection Module

Overview

We thought that creating a PowerShell module would be extremely complicated.  On the contrary and given our modes goal, creating such PowerShell module was quite straight forward.   By reworking slighty the initial script we have released (see here) and we have created the folder structure and the additional psd1 file needed to describe the Module.  Microsoft provides some good information on how to write PowerShell Modules which has helped us in building this really simple but really cool module  🙂

We have called this module  Test-SmtpConnection.   The module would replace the standard Telnet SMTP Test connection against an Exchange/Mail server as shown below. 

Telnet <%MAIL SERVER%> 25 
HELO 
MAIL FROM :<%SenderEmail%>
RCPT TO: <%REcipientEmail%>
DATA
Subject : Test Message
<% Your Message %>

.

As the Telnet Client is not always available or simply not allowed, the Test-SmtpConnection Module would mimic these commands and provide response returned by the mail server using exclusively PowerShell technology.

How to Install

Disclaimer

The script/PowerShell Module  is provided AS IS !  Use it at your own risk !!!  

Easy Download & Install  (Automated)

You can perform a manual installation (see below) or you can follow the instructions hereafter if you want to speed up the installation process.  If you have Powershell 5.0 or later installed on your machine, you can execute the following two PowerShell commands (as administrator).

First, you will issue the following command to download the zip file into your Downloads folder

#Download the zip file to your Downloads Folder (Change Accordingly if needed)
Invoke-WebRequest -uri https://www.c-nergy.be/downloads/PSDev/Test-SmtpConnection.zip -OutFile "$HOME\Downloads\Test-SmtpConnection.zip"

Wait for the download to complete. Then from the same PowerShell Console, the next command will extract the folder from the zip file and copy it over the final location which is c:\Program Files\windowsPowerShell\Modules

#Extract zip file and copy the extract folder to PowerShell Module Location 
Expand-Archive "$HOME\Downloads\Test-SmtpConnection.zip" -DestinationPath 'C:\Program Files\WindowsPowerShell\Modules'
 

If everything has run successfully and smoothly, you are done and you can jump to the HowTo use section….

Note : You need to have the correct administrative rights in order to be able to save the file into the correct destination folder location….

Manually Download & Install 

You can obtain the module files by downloading them from this location

Unzip the File

After downloading the zip package containing the file, you will need to unzip it first. The extracted folder should contains two files

Test-SmtpConnection.psm1 which contains the script logic 
Test-SmtpConnection.psd1  which is the module manifest and provides information about the module

Copy the Extracted Folder to the Modules Location

To make the Module available to your system, you will simply copy the folder (Test-SmtpConnection) into the following location

'C:\Program Files\WindowsPowerShell\Modules\'

The folder structure should be look like this

Test-Smtp_01

Click on Picture for Better Resolution

The Folder Test-SmtpConnection should contains the following two files as depicted hereafter

Test-Smtp_02

Click on Picture for Better Resolution

 

And you are done !  You can now move to the next section to see how easy it is to use this new cmdlet…..

How to Use

Usage is really straight forward !  Since we have created a PowerShell Script module, a new cmdlet will be available in your PowerShell console and you do not need to import any modules.  To check and to get used to the new cmdlet, simply issue the following command in the Powershell Console 

Get-Help Test-SmtpConnection

Test-Smtp_03

Click on Picture for Better Resolution

After you can simply issue the following command to see that the module is loaded in your PowerShell Console

Get-Module Test-SmtpConnection

Test-Smtp_04

Click on Picture for Better Resolution

The easiest way to use this PowerShell Module consist of simply issuing the cmdlet

Test-SmtpConnection

Press Enter. You will then be prompted for some additional information (the ServerName, the Sender Email address and the Recipient Email Addres)  and the script will try to perform the telnet SMTP connection.

Test-Smtp_05

Click on Picture for Better Resolution

You can also use a one liner by issuing the following command to be executed

Test-SmtpConnection -RemoteHost <%Mail_Server_Name%> -From <%SenderEmailAddress%> -To <%RecipientEmailAddress%>

Test-Smtp_06

Click on Picture for Better Resolution

You have other options that can be specified like Port or Authentication Method (HELO or EHLO).  These parameters are not mandatory and will be using default values specified in the script. 

  • Default value for Port is set to 25
  • Authentication method is set to HELO
  • Default Message is generated using Date & Time Subject

PowerShell Script Module Files

The Test-SmtpConnection Module consists of two files

  • Test-SmtpConnection.psm1 which is basically the script reformatted accordingly
  • Test-SmtpConnection.psd1  which is the module manifest and provides information about the module

We are publishing the content of these file hereafter so anyone can see what the script is doing and can help you decide to use this Module or not

Test-SmtpConnection.psm1 file

#-------------------------------------------------------------------------#
# Script_Name : Test-SmtpConnection PowerShell Module
# Description : Emulate telnet SMTP test connection
# Date : July 2020
# Written by : Griffon 
# 
# WebSite :http://www.c-nergy.be - http://www.c-nergy.be/blog
# Version : 1.0
#
# Notes: Fork from initial script of Glen Scales
#
# Disclaimer : Script provided AS IS. Use it at your own risk....
# You can use this script and distribute it as long as credits are kept 
# in place and unchanged 
#-------------------------------------------------------------------------#

<#
.Synopsis
Emulate Telnet connection to Exchange Server using Powershell.

.Description
Mimic telnet SMTP Commands (HELO/MAIL FROM/RCPT TO/DATA..) and provide response returned by the mail server
using exclusively PowerShell technology. Alternative solution if Telnet Client not installed or not available

.Link
http://c-nergy.be/blog/?p=15365
https://www.c-nergy.be/products.html

.Parameter RemoteHost
Server or IP address of the Exchange/SMTP Server.

.Parameter Port
Port to connect To. Default Port is 25.

.Parameter From
Email address of the Sender.

.Parameter To
Email address of the Recipient.

.Parameter Subject
Default Subject set to Test Message + Time. Can provide your own Subject for the message.

.Parameter HEL
Default is set to HELO but if preferred EHLO value can be passed.

.Example
Minium Parameters to initiate smtp connection. 
Test-SmtpConnection -RemoteHost 10.10.10.10 -From demo@test.com -To Target@test.com

.Example
Set a custom Subject Message.
Test-SmtpConnection -RemoteHost 10.10.10.10 -From demo@test.com -To Target@test.com -Subject "This is a test Message"

.Example
Use EHLO instead of HELO.
Test-SmtpConnection -RemoteHost 10.10.10.10 -From demo@test.com -To Target@test.com -Subject "This is a test Message" -HEL EHLO
#>

# written By Griffon - July 2020 - www.c-nergy.be

function Test-SmtpConnection {
param(
[Parameter(Mandatory=$true)] [String] $remotehost,
[Parameter(Mandatory=$true)] [String] $From,
[Parameter(Mandatory=$true)] [String] $To,
$port="25",
[String] $Subject="Test Message $(get-date)",
[String] $HEL="HELO"
)

# -Default BODY MESSAGE USED WHEN MESSAGE IS SEND 
$testMsg=@"
DATA
Subject: $Subject

This is a test Message

.

"@

function readResponse {

while($stream.DataAvailable) 
{ 
$read = $stream.Read($buffer, 0, 1024) 
write-host -n -foregroundcolor cyan ($encoding.GetString($buffer, 0, $read)) 
""
} 
}

#------------------------------------#
# CODE TO PERFORM SMTP CONNECTION #
#------------------------------------#

$socket = new-object System.Net.Sockets.TcpClient($remoteHost, $port)

if($socket -eq $null) { return; }

$stream = $socket.GetStream() 
$writer = new-object System.IO.StreamWriter($stream) 
$buffer = new-object System.Byte[] 1024 
$encoding = new-object System.Text.AsciiEncoding 
readResponse($stream)

#-------------------------------------------------------#
# SMTP COMMAND HELO OR EHLO - DEFAULT IS HELO #
#-------------------------------------------------------#

write-host -foregroundcolor yellow $HEL
""
$writer.WriteLine($HEL) 
$writer.Flush()
start-sleep -m 500 
readResponse($stream)


#---------------------------------------------------#
# SMTP COMMAND Mail FROM #
#---------------------------------------------------#


$command = "MAIL FROM: $from" 
write-host -foregroundcolor yellow "MAIL FROM: $from" 
$writer.WriteLine($command) 
$writer.Flush()
start-sleep -m 500 
readResponse($stream)


#---------------------------------------------------#
# SMTP COMMAND RCPT TO #
#---------------------------------------------------#

$command = "RCPT TO: $To"
write-host -foregroundcolor yellow $command
$writer.WriteLine($command) 
$writer.Flush()
start-sleep -m 500 
readResponse($stream)

#---------------------------------------------------#
# SMTP COMMAND DATA #
#---------------------------------------------------#
write-host -foregroundcolor yellow $testMsg
$writer.WriteLine($testMsg) 
$writer.Flush()
start-sleep -m 500 
readResponse($stream)

#---------------------------------------------------#
# CLOSING SMTP CONNECTION #
#---------------------------------------------------#

$command = "QUIT" 
write-host -foregroundcolor yellow $command
""
$writer.WriteLine($command) 
$writer.Flush()
start-sleep -m 500 
readResponse($stream)
## Close the streams 
$writer.Close() 
$stream.Close()

}

Export-ModuleMember -Function Test-SmtpConnection

Test-SmtpConnection.psd1 file

The content of the psd1 file is shown hereafter.

@{
RootModule = 'Test-SmtpConnection.psm1'
ModuleVersion = '1.0.0'
Description= 'Emulate a Telnet SMTP connection to Exchange server'
Author = 'Griffon - www.c-nergy.be'
PowerShellVersion = '3.0'
FunctionsToExport="*"
HelpInfoURI = 'http://c-nergy.be/blog/?p=15266'
}

Final Notes

This is it for this post ! 

We hope that you will enjoy this new cmdlet.  This PowerShell script is now part of our Troubleshooting Toolkit because it’ s really easy to install and use and offer really a good alternative to the venerable Telnet solution.   If you wish to provide feedback on it, do not hesitate.    At a later stage, as mentioned earlier, we might want to publish this module into the PowerShell Gallery to further ease the distribution

Till next time

See ya

 

Leave a Reply