"PoshMailKit" Release version 1.1.0 published to Gallery

I've published the release of PoshMailKit (1.1.0). You can install it using this command:

Install-Module -Name PoshMailKit

Or, you can check it out on GitHub.

v1.0 is here!

Looks like cause to celebrate

Everything that worked in Send-MailMessage should be working in version 1.0 of Send-MKMailMessage. I'm not going to beat on a dead beehive here though going over everything that's changed; just assume if it worked in the old cmdlet, it should work here as well.

Well, okay...there is one thing I want to mention: I've implemented some "Modern" versions of some of the parameters, and they're incompatible with the "Legacy" versions. Here's a brief overview of those changes and why I made them (note that all legacy parameters are still available):

• BodyAsHtml -> BodyFormat
  • The BodyAsHtml parameter is a simple switch to change from plain text to an HTML-formatted body, but there are other formats available from MailKit. Because of this, I've added BodyFormat, which takes the enum MimeKit.Text.TextFormat, which has the following options:
    • Plain
    • Text
    • Flowed
    • Html
    • Enriched
    • CompressedRichText
    • RichText
  • I don't know what one might do with the rest of the options, but if you find a use for them, they're available to you
• DeliveryNotificationOption -> DeliveryStatusNotification
  • The legacy version uses a flag enum that's part of System.Net.Mail, which I decided I didn't want to rely on for two reasons:
    • Since other parts of System.Net.Mail have been known to have issues, I don't want to expect this will stick around in the future
    • Two of the options (OnSuccess and OnFailure) do not actually correspond directly to the flags that are added by the client (which are actually Success and Failure, respectively)
  • The new version works the same way but uses the MailKit version of the enum, which uses names that correspond directly to the flags added to the email on send
  • This may seem a bit pedantic, but I do like when things are "correct" and actually match what they're supposed to do properly
• Encoding -> CharsetEncoding and ContentTransferEncoding
  • Encoding technically sets two things and is kind of limited to what the Send-MailMessage devs defined for allowed encodings.
  • The new pair of parameters allows you to both set the text encoding as well as the transfer encoding; I'll be honest, I'm not sure what you'd use that for, but if you need a transfer encoding other than QuotedPrintable or Base64, the old Encoding has no way for you to do that. It also has no way for you to use character encodings other than the handful it defines (though they're probably more than adequate for almost all uses).
• Priority -> MessagePriority
  • This is another one that is probably me being a bit pedantic, but the options for Priority don't actually match what gets set in the message header
  • MessagePriority's options are an exact match for what is set in the header
  • Priority's Low and High priorities are replaced with the (more accurate) NonUrgent and Urgent priorities in MessagePriority; both still use Normal for the default priority
• UseSsl -> SecureSocketOptions
  • The legacy switch was just an on-off switch and doesn't let you specify which kind of secure connection you want to use; additionally, by default, Send-MailMessage won't attempt a secure connection at all, only if you specify -UseSsl
  • The modern version allows you to select from the following options:
    • None: No SSL or TLS encryption will be attempted
    • Auto: Allows Send-MKMailMessage to determine which SSL or TLS option to use; if the server doesn't support either, then it will continue without encryption
    • SslOnConnect: Establishes an SSL/TLS encryption tunnel to the server before connecting; this should only be used if the connection port itself is encrypted, which is not the typical modern configuration as StartTLS is generally superior
    • StartTls: Connects to the server as normal and issues a StartTLS command to elevate the connection to use TLS encryption after reading the greetings and capabilities of the server; if the server doesn't support StartTLS, the connection will fail
    • StartTlsWhenAvailable: Same as StartTls, but will proceed without TLS if the server doesn't support it
  • The default for Send-MKMailMessage in Modern mode is Auto, while the default in Legacy mode is None; this means if you were using Send-MailMessage to send to a server that supports StartTLS but has an untrusted certificate, but also allows unsecured email, it probably worked fine before but will fail with Send-MKMailMessage in Modern mode. You can either set SecureSocketOptions to None or add the Legacy switch to get around this.

Please note that the use of any Modern variant parameters will disable all Legacy variants, so you can't use Encoding at the same time as SecureSocketOptions, for example. Using any Legacy variant will switch the cmdlet into Legacy mode to better match the expected behavior of Send-MailMessage. If you're trying to drop this in as a replacement for Send-MailMessage and it's not working the same, you can try adding the Legacy switch to see if that fixes it (if not, please open an issue on the project's GitHub repo with as much detail as necessary to replicate the issue with whatever errors you're getting so I can try to correct that).

Wait...1.1?

New features? Didn't it just release?

Okay, so, technically all I was expecting from the 1.0 branch was bugfix, so 1.0.1, 1.0.2, you get the idea. Fixing two of the initial issues I discovered with 1.0, though, one is arguably added functionality, and the other definitely added a capability that I didn't include initially, so I've decided to bump it to 1.1.0. With that, I've made the following changes:

• Fixed a bug with relative paths on network shares for attachments; seems PowerShell gives some extra bits to the path it reports when coming from a network share, at least sometimes, so I'm now looking for and stripping that out.
• Fixed support for Delivery Notifications: initially I didn't realize you could specify multiple options and that they were separate flags being added to the email, so I didn't support that correctly in either Legacy or Modern versions. This is fixed; arguably, it could have been considered either new functionality (since it didn't support it initially) or a bugfix (since it really should have).
• Fixed UseSsl: when specifying that switch, it technically just left the Secure Socket option set to the default of Auto, which would work fine if the server you're connecting to supports encryption but would just silently work anyway if it doesn't, which is not the correct or expected behavior. To fix this, I added a new Modern mode switch parameter: RequireSecureConnection, which will be treated as set to True if UseSsl is specified. I set this up as a separate switch parameter because it allows someone to use Auto to automatically determine the best connection type to use in Modern mode while still requiring the connection to be a secure one, which was not previously available. This is inarguably new functionality, though, so this is why I bumped it up to 1.1.

2.0 roadmap

There are a few things I'm looking at doing for the initial 2.0 release, the chief among them is moving the project to .NET 6. This will, unfortunately, mean no longer supporting Windows PowerShell 5.1, though. I don't want to abandon legacy Windows PowerShell, though, so I'm looking into how to best move forward while still keeping the 1.x line alive while PS 5.1 remains relevant. Right now my main thoughts on it are to split it off into a Legacy project (though I'll still maintain Legacy mode for the 2.x line).

So far I have a pre-release version working in the Dev channel that's moved to .NET 6 at this point; the only things I have outstanding for that at this time are documentation and decision making tasks, though I might decide to add more before publishing 2.0.

Image attribution

See links to origin sites for proper attribution to creators

• Bear mailbox
  • Linked to from this blog post
  • Modified to remove border

The rest I made myself (poorly), with the use of public domain clipart