Skip to content

Commit

Permalink
Add suggestions for replacements (#10711)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sdwheeler
sdwheeler authored Dec 4, 2023
1 parent 4ed7d80 commit b32b394
Show file tree
Hide file tree
Showing 4 changed files with 212 additions and 73 deletions.
73 changes: 54 additions & 19 deletions reference/5.1/Microsoft.PowerShell.Utility/Send-MailMessage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Utility
ms.date: 12/12/2022
ms.date: 12/04/2023
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/send-mailmessage?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Send-MailMessage
Expand Down Expand Up @@ -32,10 +32,11 @@ The `Send-MailMessage` cmdlet sends an email message from within PowerShell.
You must specify a Simple Mail Transfer Protocol (SMTP) server or the `Send-MailMessage` command
fails. Use the **SmtpServer** parameter or set the `$PSEmailServer` variable to a valid SMTP server.
The value assigned to `$PSEmailServer` is the default SMTP setting for PowerShell. For more
information, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md).
information, see
[about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md).

> [!WARNING]
> The `Send-MailMessage` cmdlet is obsolete. This cmdlet does not guarantee secure connections to
> The `Send-MailMessage` cmdlet is obsolete. This cmdlet doesn't guarantee secure connections to
> SMTP servers. While there is no immediate replacement available in PowerShell, we recommend you do
> not use `Send-MailMessage`. For more information, see
> [Platform Compatibility note DE0005](https://aka.ms/SendMailMessage).
Expand All @@ -51,44 +52,68 @@ uses the default `$PSEmailServer` variable for the SMTP server, so the **SmtpSer
not needed.

```powershell
Send-MailMessage -From 'User01 <[email protected]>' -To 'User02 <[email protected]>' -Subject 'Test mail'
$sendMailMessageSplat = @{
From = 'User01 <[email protected]>'
To = 'User02 <[email protected]>'
Subject = 'Test mail'
}
Send-MailMessage @sendMailMessageSplat
```

The `Send-MailMessage` cmdlet uses the **From** parameter to specify the message's sender. The
**To** parameter specifies the message's recipient. The **Subject** parameter uses the text string
**Test mail** as the message because the optional **Body** parameter is not included.
**Test mail** as the message because the optional **Body** parameter isn't included.

### Example 2: Send an attachment

This example sends an email message with an attachment.

```powershell
Send-MailMessage -From 'User01 <[email protected]>' -To 'User02 <[email protected]>', 'User03 <[email protected]>' -Subject 'Sending the Attachment' -Body "Forgot to send the attachment. Sending now." -Attachments .\data.csv -Priority High -DeliveryNotificationOption OnSuccess, OnFailure -SmtpServer 'smtp.fabrikam.com'
$sendMailMessageSplat = @{
From = 'User01 <[email protected]>'
To = 'User02 <[email protected]>', 'User03 <[email protected]>'
Subject = 'Sending the Attachment'
Body = "Forgot to send the attachment. Sending now."
Attachments = '.\data.csv'
Priority = 'High'
DeliveryNotificationOption = 'OnSuccess', 'OnFailure'
SmtpServer = 'smtp.fabrikam.com'
}
Send-MailMessage @sendMailMessageSplat
```

The `Send-MailMessage` cmdlet uses the **From** parameter to specify the message's sender. The
**To** parameter specifies the message's recipients. The **Subject** parameter describes the content
of the message. The **Body** parameter is the content of the message.

The **Attachments** parameter specifies the file in the current directory that is attached to the
email message. The **Priority** parameter sets the message to **High** priority. The
**-DeliveryNotificationOption** parameter specifies two values, **OnSuccess** and **OnFailure**. The
The **Attachments** parameter specifies the file in the current directory that's attached to the
email message. The **Priority** parameter sets the message to `High` priority. The
**DeliveryNotificationOption** parameter specifies two values, `OnSuccess` and `OnFailure`. The
sender will receive email notifications to confirm the success or failure of the message delivery.
The **SmtpServer** parameter sets the SMTP server to **smtp.fabrikam.com**.
The **SmtpServer** parameter sets the SMTP server to `smtp.fabrikam.com`.

### Example 3: Send email to a mailing list

This example sends an email message to a mailing list.

```powershell
Send-MailMessage -From 'User01 <[email protected]>' -To 'ITGroup <[email protected]>' -Cc 'User02 <[email protected]>' -Bcc 'ITMgr <[email protected]>' -Subject "Don't forget today's meeting!" -Credential domain01\admin01 -UseSsl
$sendMailMessageSplat = @{
From = 'User01 <[email protected]>'
To = 'ITGroup <[email protected]>'
Cc = 'User02 <[email protected]>'
Bcc = 'ITMgr <[email protected]>'
Subject = "Don't forget today's meeting!"
Credential = 'domain01\admin01'
UseSsl = $true
}
Send-MailMessage @sendMailMessageSplat
```

The `Send-MailMessage` cmdlet uses the **From** parameter to specify the message's sender. The
**To** parameter specifies the message's recipients. The **Cc** parameter sends a copy of the
message to the specified recipient. The **Bcc** parameter sends a blind copy of the message. A blind
copy is an email address that is hidden from the other recipients. The **Subject** parameter is the
message because the optional **Body** parameter is not included.
copy is an email address that's hidden from the other recipients. The **Subject** parameter is the
message because the optional **Body** parameter isn't included.

The **Credential** parameter specifies a domain administrator's credentials are used to send the
message. The **UseSsl** parameter specifies that Secure Socket Layer (SSL) creates a secure
Expand All @@ -115,8 +140,8 @@ Accept wildcard characters: False
### -Bcc
Specifies the email addresses that receive a copy of the mail but are not listed as recipients of
the message. Enter names (optional) and the email address, such as `Name <[email protected]>`.
Specifies the email addresses that receive a copy of the mail but aren't listed as recipients of the
message. Enter names (optional) and the email address, such as `Name <[email protected]>`.

```yaml
Type: System.String[]
Expand Down Expand Up @@ -325,7 +350,7 @@ Accept wildcard characters: False
Specifies the name of the SMTP server that sends the email message.

The default value is the value of the `$PSEmailServer` preference variable. If the preference
variable is not set and this parameter is not used, the `Send-MailMessage` command fails.
variable isn't set and this parameter isn't used, the `Send-MailMessage` command fails.

```yaml
Type: System.String
Expand All @@ -341,7 +366,7 @@ Accept wildcard characters: False

### -Subject

The **Subject** parameter is required. This parameter specifies the subject of the email message.
The **Subject** parameter isn't required. This parameter specifies the subject of the email message.

```yaml
Type: System.String
Expand Down Expand Up @@ -375,7 +400,7 @@ Accept wildcard characters: False
### -UseSsl

The Secure Sockets Layer (SSL) protocol is used to establish a secure connection to the remote
computer to send mail. By default, SSL is not used.
computer to send mail. By default, SSL isn't used.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand All @@ -393,7 +418,8 @@ Accept wildcard characters: False

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
-WarningAction, and -WarningVariable. For more information, see
[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

Expand All @@ -409,6 +435,15 @@ This cmdlet returns no output.

## NOTES

The `Send-MailMessage` cmdlet is obsolete. For more information, see
[Platform Compatibility note DE0005](https://aka.ms/SendMailMessage). This cmdlet doesn't guarantee
secure connections to SMTP servers.

_DE0005_ suggests using the third-party library, [MailKit](http://www.mimekit.net/). If you are
using Exchange Online, you can use the
[Send-MgUserMail](/powershell/module/microsoft.graph.users.actions/send-mgusermail) from the
Microsoft Graph PowerShell SDK.

## RELATED LINKS

[about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md)
Expand Down
71 changes: 53 additions & 18 deletions reference/7.2/Microsoft.PowerShell.Utility/Send-MailMessage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Utility
ms.date: 12/12/2022
ms.date: 12/04/2023
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/send-mailmessage?view=powershell-7.2&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Send-MailMessage
Expand Down Expand Up @@ -32,10 +32,11 @@ The `Send-MailMessage` cmdlet sends an email message from within PowerShell.
You must specify a Simple Mail Transfer Protocol (SMTP) server or the `Send-MailMessage` command
fails. Use the **SmtpServer** parameter or set the `$PSEmailServer` variable to a valid SMTP server.
The value assigned to `$PSEmailServer` is the default SMTP setting for PowerShell. For more
information, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md).
information, see
[about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md).

> [!WARNING]
> The `Send-MailMessage` cmdlet is obsolete. This cmdlet does not guarantee secure connections to
> The `Send-MailMessage` cmdlet is obsolete. This cmdlet doesn't guarantee secure connections to
> SMTP servers. While there is no immediate replacement available in PowerShell, we recommend you do
> not use `Send-MailMessage`. For more information, see
> [Platform Compatibility note DE0005](https://aka.ms/SendMailMessage).
Expand All @@ -51,44 +52,68 @@ uses the default `$PSEmailServer` variable for the SMTP server, so the **SmtpSer
not needed.

```powershell
Send-MailMessage -From 'User01 <[email protected]>' -To 'User02 <[email protected]>' -Subject 'Test mail'
$sendMailMessageSplat = @{
From = 'User01 <[email protected]>'
To = 'User02 <[email protected]>'
Subject = 'Test mail'
}
Send-MailMessage @sendMailMessageSplat
```

The `Send-MailMessage` cmdlet uses the **From** parameter to specify the message's sender. The
**To** parameter specifies the message's recipient. The **Subject** parameter uses the text string
**Test mail** as the message because the optional **Body** parameter is not included.
**Test mail** as the message because the optional **Body** parameter isn't included.

### Example 2: Send an attachment

This example sends an email message with an attachment.

```powershell
Send-MailMessage -From 'User01 <[email protected]>' -To 'User02 <[email protected]>', 'User03 <[email protected]>' -Subject 'Sending the Attachment' -Body "Forgot to send the attachment. Sending now." -Attachments .\data.csv -Priority High -DeliveryNotificationOption OnSuccess, OnFailure -SmtpServer 'smtp.fabrikam.com'
$sendMailMessageSplat = @{
From = 'User01 <[email protected]>'
To = 'User02 <[email protected]>', 'User03 <[email protected]>'
Subject = 'Sending the Attachment'
Body = "Forgot to send the attachment. Sending now."
Attachments = '.\data.csv'
Priority = 'High'
DeliveryNotificationOption = 'OnSuccess', 'OnFailure'
SmtpServer = 'smtp.fabrikam.com'
}
Send-MailMessage @sendMailMessageSplat
```

The `Send-MailMessage` cmdlet uses the **From** parameter to specify the message's sender. The
**To** parameter specifies the message's recipients. The **Subject** parameter describes the content
of the message. The **Body** parameter is the content of the message.

The **Attachments** parameter specifies the file in the current directory that is attached to the
email message. The **Priority** parameter sets the message to **High** priority. The
**-DeliveryNotificationOption** parameter specifies two values, **OnSuccess** and **OnFailure**. The
The **Attachments** parameter specifies the file in the current directory that's attached to the
email message. The **Priority** parameter sets the message to `High` priority. The
**DeliveryNotificationOption** parameter specifies two values, `OnSuccess` and `OnFailure`. The
sender will receive email notifications to confirm the success or failure of the message delivery.
The **SmtpServer** parameter sets the SMTP server to **smtp.fabrikam.com**.
The **SmtpServer** parameter sets the SMTP server to `smtp.fabrikam.com`.

### Example 3: Send email to a mailing list

This example sends an email message to a mailing list.

```powershell
Send-MailMessage -From 'User01 <[email protected]>' -To 'ITGroup <[email protected]>' -Cc 'User02 <[email protected]>' -Bcc 'ITMgr <[email protected]>' -Subject "Don't forget today's meeting!" -Credential domain01\admin01 -UseSsl
$sendMailMessageSplat = @{
From = 'User01 <[email protected]>'
To = 'ITGroup <[email protected]>'
Cc = 'User02 <[email protected]>'
Bcc = 'ITMgr <[email protected]>'
Subject = "Don't forget today's meeting!"
Credential = 'domain01\admin01'
UseSsl = $true
}
Send-MailMessage @sendMailMessageSplat
```

The `Send-MailMessage` cmdlet uses the **From** parameter to specify the message's sender. The
**To** parameter specifies the message's recipients. The **Cc** parameter sends a copy of the
message to the specified recipient. The **Bcc** parameter sends a blind copy of the message. A blind
copy is an email address that is hidden from the other recipients. The **Subject** parameter is the
message because the optional **Body** parameter is not included.
copy is an email address that's hidden from the other recipients. The **Subject** parameter is the
message because the optional **Body** parameter isn't included.

The **Credential** parameter specifies a domain administrator's credentials are used to send the
message. The **UseSsl** parameter specifies that Secure Socket Layer (SSL) creates a secure
Expand All @@ -115,8 +140,8 @@ Accept wildcard characters: False
### -Bcc
Specifies the email addresses that receive a copy of the mail but are not listed as recipients of
the message. Enter names (optional) and the email address, such as `Name <[email protected]>`.
Specifies the email addresses that receive a copy of the mail but aren't listed as recipients of the
message. Enter names (optional) and the email address, such as `Name <[email protected]>`.

```yaml
Type: System.String[]
Expand Down Expand Up @@ -351,7 +376,7 @@ Accept wildcard characters: False
Specifies the name of the SMTP server that sends the email message.

The default value is the value of the `$PSEmailServer` preference variable. If the preference
variable is not set and this parameter is not used, the `Send-MailMessage` command fails.
variable isn't set and this parameter isn't used, the `Send-MailMessage` command fails.

```yaml
Type: System.String
Expand Down Expand Up @@ -401,7 +426,7 @@ Accept wildcard characters: False
### -UseSsl

The Secure Sockets Layer (SSL) protocol is used to establish a secure connection to the remote
computer to send mail. By default, SSL is not used.
computer to send mail. By default, SSL isn't used.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand All @@ -419,7 +444,8 @@ Accept wildcard characters: False

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
-WarningAction, and -WarningVariable. For more information, see
[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

Expand All @@ -435,6 +461,15 @@ This cmdlet returns no output.

## NOTES

The `Send-MailMessage` cmdlet is obsolete. For more information, see
[Platform Compatibility note DE0005](https://aka.ms/SendMailMessage). This cmdlet doesn't guarantee
secure connections to SMTP servers.

_DE0005_ suggests using the third-party library, [MailKit](http://www.mimekit.net/). If you are
using Exchange Online, you can use the
[Send-MgUserMail](/powershell/module/microsoft.graph.users.actions/send-mgusermail) from the
Microsoft Graph PowerShell SDK.

## RELATED LINKS

[about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md)
Expand Down
Loading

0 comments on commit b32b394

Please sign in to comment.