Skip to content

SMTP

Pode has an inbuilt SMTP server for receiving emails, with support for non-TLS as well as implicit and explicit TLS. Unlike with web servers that use the Route functions, an SMTP server use the Handler functions, which let you specify logic for handling responses from TCP streams.

Tip

You can setup multiple different Handlers to run different logic for one email.

Usage

To create a Handler for the SMTP server you can use the following example:

Start-PodeServer {
    Add-PodeEndpoint -Address * -Port 25 -Protocol Smtp

    Add-PodeHandler -Type Smtp -Name 'Main' -ScriptBlock {
        Write-Host $SmtpEvent.Email.From
        Write-Host $SmtpEvent.Email.To
        Write-Host $SmtpEvent.Email.Body
    }
}

Starting this server will listen for incoming email on localhost:25. The Handler will have access to an $SmtpEvent object (see below), which contains information about the received email.

An example of sending an email to the above server via Send-MailMessage:

Send-MailMessage -SmtpServer localhost -To 'to@example.com' -From 'from@example.com' -Body 'Hello' -Subject 'Hi there' -Port 25

TLS

You can enable TLS for your endpoints by supplying the normal relevant certificates parameters on Add-PodeEndpoint, and setting the -Protocol to Smtps. You can also toggle between implicit and explicit TLS by using the -TlsMode parameter.

By default the TLS mode is implicit, and the default port for implicit TLS is 465; for explicit TLS it's 587. These can of course be customised using -Port.

Start-PodeServer {
    Add-PodeEndpoint -Address * -Protocol Smtps -SelfSigned -TlsMode Explicit
    Add-PodeEndpoint -Address * -Protocol Smtps -SelfSigned -TlsMode Implicit

    Add-PodeHandler -Type Smtp -Name 'Main' -ScriptBlock {
        Write-Host $SmtpEvent.Email.From
        Write-Host $SmtpEvent.Email.To
        Write-Host $SmtpEvent.Email.Body
    }
}

.NET only supports explicit TLS, so an example of sending an email to the explicit TLS endpoint, on port 587, is as follows:

# if using a self signed cert, make sure to run the below
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { return $true }

# send the email
Send-MailMessage -SmtpServer localhost -To 'to@pode.com' -From 'from@pode.com' -Body 'Hello' -Subject 'Hi there' -Port 587 -UseSSL

Attachments

The SMTP server also accepts attachments, which are available in a Handler via $SmtpEvent.Email.Attachments. This property contains a list of available attachments on the Email, each attachment has a Name and Bytes properties - the latter being the raw byte content of the attachment.

An attachment also has a .Save(<path>) method. For example, if the Email has an a single attachment: an example.png file, and you wish to save it, then the following will save the file to C:\temp\example.png:

Add-PodeHandler -Type Smtp -Name 'Main' -ScriptBlock {
    $SmtpEvent.Email.Attachments[0].Save('C:\temp')
}

Objects

SmtpEvent

The SMTP Handler will be passed the $SmtpEvent object, that contains the Request, Response, and Email properties:

Name Type Description
Request object The raw Request object
Response object The raw Response object
Lockable hashtable A synchronized hashtable that can be used with Lock-PodeObject
Email hashtable An object containing data from the email, as seen below
Endpoint hashtable Contains the Address and Protocol of the endpoint being hit - such as "pode.example.com" or "127.0.0.2", or HTTP or HTTPS for the Protocol
Timestamp datetime The current date and time of the Request

Email

The Email property contains the following properties:

Name Type Description
From string The email address of the person sending the email
To string[] The email addresses receiving the email (this is to, cc, and bcc)
Subject string The subject of the email
Body string The body of the email, decoded depending on content type/encoding
IsUrgent boolean This will be true if the Priority/Importance of the email is High, otherwise false
ContentType string The content type of the original email body
ContentEncoding string The content encoding of the original email body
Headers hashtable A list of all the headers received for the email
Data string The full raw data of the email
Attachments PodeSmtpAttachment[] An list of SMTP attachments, containing the Name and Bytes of the attachment
Back to top