Send-MailMessage sends email from PowerShell through an SMTP server, but Microsoft marks the cmdlet obsolete and warns that it does not guarantee secure SMTP connections. It can still be useful for understanding or maintaining existing scripts; for new work, choose an approach that fits the mail system and its authentication requirements.
What Send-MailMessage does and what you need
The cmdlet submits a message through an SMTP server. You must supply a server with -SmtpServer or set the $PSEmailServer preference variable; without either, the command fails. The -SmtpServer parameter takes precedence over that default. See Microsoft’s Send-MailMessage reference for the documented syntax and examples.
You also need sender and recipient addresses. Your mail administrator or provider must tell you the correct SMTP host, port, authentication method, and TLS requirements. The cmdlet reference does not establish settings for any particular provider or relay.
Send a basic message
Specify the sender, recipient, subject, and SMTP server. The subject is optional, but is useful for most messages.
#1 Best Overall
- Book - powershell for sysadmins: workflow automation made easy
- Language: english
- Binding: paperback
$sendMailMessageSplat = @{
From = 'User01 <user01@fabrikam.com>'
To = 'User02 <user02@fabrikam.com>'
Subject = 'Test mail'
SmtpServer = 'smtp.example.com'
}
Send-MailMessage @sendMailMessageSplatReplace the example addresses and host with values appropriate to your environment. To provide a message body, add Body to the hashtable:
$sendMailMessageSplat.Body = 'This is a test message.'
Send-MailMessage @sendMailMessageSplatThe cmdlet returns no output. A lack of output alone does not confirm delivery; check the SMTP server or your mail system for delivery status when needed.
Add recipients, HTML, or an attachment
CC and BCC recipients
Use -Cc and -Bcc to add copy and blind-copy recipients. These parameters accept address values; add them to the splat alongside To.
HTML body
Set -BodyAsHtml when the value supplied to -Body contains HTML markup:
Rank #3
$sendMailMessageSplat.Body = '<p>Status: <strong>complete</strong></p>'
$sendMailMessageSplat.BodyAsHtml = $true
Send-MailMessage @sendMailMessageSplatFile attachment
Pass a file path or paths to -Attachments. For example:
$sendMailMessageSplat.Attachments = 'C:Reportssummary.csv'
Send-MailMessage @sendMailMessageSplatMicrosoft’s examples also show that attachment paths can be piped as strings. Ensure the script can access the file at the path it supplies.
SMTP port, credentials, and SSL
The cmdlet supports -Port, -Credential, and -UseSsl. These switches do not determine the settings your server requires: obtain its supported port, authentication method, and TLS configuration from the administrator or service documentation. For example, if the relay requires credentials and SSL, add the corresponding values:
$sendMailMessageSplat.Port = 587
$sendMailMessageSplat.UseSsl = $true
$sendMailMessageSplat.Credential = Get-Credential
Send-MailMessage @sendMailMessageSplatThe port above is an example value, not a universal SMTP setting. Likewise, enabling -UseSsl does not establish that a connection meets a particular server’s security requirements. Microsoft specifically warns that the cmdlet does not guarantee secure connections to SMTP servers.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Best Value
Why Microsoft marks the cmdlet obsolete
Microsoft’s reference labels it obsolete and states: “This cmdlet doesn’t guarantee secure connections to SMTP servers.” Treat that as a reason to review existing scripts and their authentication and transport-security assumptions, not as proof that every SMTP server will reject the cmdlet. Compatibility and security depend on the server, tenant policy, authentication method, and implementation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose an alternative for new or migrated scripts
Microsoft says there is no immediate built-in replacement. Its guidance points to different options depending on the system you are sending through; neither should be assumed to be a drop-in substitute.
| Approach | Best fit | What to account for |
|---|---|---|
Continue using Send-MailMessage |
Maintaining an existing script that still works with its SMTP server. | Review the server’s authentication and TLS requirements and the cmdlet’s security warning. The reference does not guarantee secure connections. |
| MailKit | SMTP-oriented workflows where a third-party library is acceptable. | MailKit is a third-party library, not a built-in cmdlet replacement. Plan and validate its authentication, TLS, and message-handling implementation against the target server. |
Send-MgUserMail |
Mail sent through Exchange Online using the Microsoft Graph PowerShell SDK. | This uses Microsoft Graph rather than SMTP. Account for Graph access and tenant requirements; it is not a general SMTP relay replacement. |
For Exchange Online, Microsoft points to Send-MgUserMail. For SMTP-oriented workflows, Microsoft’s compatibility guidance names the third-party MailKit library. Decide based on whether the destination is a mailbox service or an SMTP relay, and verify the required authentication method, security settings, and message features before migrating.
Other documented parameters
Beyond addressing, body, attachments, server, port, credentials, and SSL, the cmdlet syntax includes -Encoding, -DeliveryNotificationOption, -Priority, and -ReplyTo. Microsoft’s examples also demonstrate mailing-list delivery, priority, delivery notifications, credentials, and SSL. Consult the parameter reference for accepted values and details before relying on a less common option.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
