Send-MailMessage
Sends an email message.
Syntax
All
Send-MailMessage
[[-Body] <String>]
[[-SmtpServer] <String>]
[[-Subject] <String>]
[-To] <String[]>
-From <String>
[-Attachments <String[]>]
[-Bcc <String[]>]
[-BodyAsHtml]
[-Encoding <Encoding>]
[-Cc <String[]>]
[-DeliveryNotificationOption <DeliveryNotificationOptions>]
[-Priority <MailPriority>]
[-ReplyTo <String[]>]
[-Credential <PSCredential>]
[-UseSsl]
[-Port <Int32>]
[<CommonParameters>]
Description
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.
Warning
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.
Examples
Example 1: Send an email from one person to another person
This example sends an email message from one person to another person.
The From, To, and Subject parameters are required by Send-MailMessage. This example
uses the default $PSEmailServer variable for the SMTP server, so the SmtpServer parameter is
not needed.
$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 isn't included.
Example 2: Send an attachment
This example sends an email message with an attachment.
$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'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.
Example 3: Send email to a mailing list
This example sends an email message to a mailing list.
$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'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 connection.
Parameters
-Attachments
Specifies the path and file names of files to be attached to the email message. You can use this
parameter or pipe the paths and file names to Send-MailMessage.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | PsPath |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Bcc
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]>.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Body
Specifies the content of the email message.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 2 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-BodyAsHtml
Specifies that the value of the Body parameter contains HTML.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | BAH |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Cc
Specifies the email addresses to which a carbon copy (CC) of the email message is sent. Enter names
(optional) and the email address, such as Name <[email protected]>.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Credential
Specifies a user account that has permission to perform this action. The default is the current user.
Type a user name, such as User01 or Domain01\User01. Or, enter a PSCredential object,
such as one from the Get-Credential cmdlet.
Credentials are stored in a PSCredential object and the password is stored as a SecureString.
Note
For more information about SecureString data protection, see How secure is SecureString?.
Parameter properties
| Type: | PSCredential |
| Default value: | Current user |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-DeliveryNotificationOption
Specifies the delivery notification options for the email message. You can specify multiple values. None is the default value. The alias for this parameter is DNO.
The delivery notifications are sent to the address in the From parameter.
The acceptable values for this parameter are as follows:
None: No notification.OnSuccess: Notify if the delivery is successful.OnFailure: Notify if the delivery is unsuccessful.Delay: Notify if the delivery is delayed.Never: Never notify.
These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the DeliveryNotification parameter as an array of values or as a comma-separated string of those values. The cmdlet will combine the values using a binary-OR operation. Passing values as an array is the simplest option and also allows you to use tab-completion on the values.
Parameter properties
| Type: | DeliveryNotificationOptions |
| Default value: | None |
| Accepted values: | None, OnSuccess, OnFailure, Delay, Never |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | DNO |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Encoding
Specifies the type of encoding for the target file. The default value is utf8NoBOM.
The acceptable values for this parameter are as follows:
ascii: Uses the encoding for the ASCII (7-bit) character set.ansi: Uses the encoding for the for the current culture's ANSI code page. This option was added in PowerShell 7.4.bigendianunicode: Encodes in UTF-16 format using the big-endian byte order.bigendianutf32: Encodes in UTF-32 format using the big-endian byte order.oem: Uses the default encoding for MS-DOS and console programs.unicode: Encodes in UTF-16 format using the little-endian byte order.utf7: Encodes in UTF-7 format.utf8: Encodes in UTF-8 format.utf8BOM: Encodes in UTF-8 format with Byte Order Mark (BOM)utf8NoBOM: Encodes in UTF-8 format without Byte Order Mark (BOM)utf32: Encodes in UTF-32 format.
Beginning with PowerShell 6.2, the Encoding parameter also allows numeric IDs of registered code
pages (like -Encoding 1251) or string names of registered code pages (like
-Encoding "windows-1251"). For more information, see the .NET documentation for
Encoding.CodePage.
Starting with PowerShell 7.4, you can use the Ansi value for the Encoding parameter to pass
the numeric ID for the current culture's ANSI code page without having to specify it manually.
Note
UTF-7* is no longer recommended to use. As of PowerShell 7.1, a warning is written if you
specify utf7 for the Encoding parameter.
Parameter properties
| Type: | Encoding |
| Default value: | ASCII |
| Accepted values: | ASCII, BigEndianUnicode, BigEndianUTF32, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32 |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | BE |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-From
The From parameter is required. This parameter specifies the sender's email address. Enter a
name (optional) and email address, such as Name <[email protected]>.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Port
Specifies an alternate port on the SMTP server. The default value is 25, which is the default SMTP port.
Parameter properties
| Type: | Int32 |
| Default value: | 25 |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Priority
Specifies the priority of the email message. Normal is the default. The acceptable values for this parameter are Normal, High, and Low.
Parameter properties
| Type: | MailPriority |
| Default value: | Normal |
| Accepted values: | Normal, High, Low |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-ReplyTo
Specifies additional email addresses (other than the From address) to use to reply to this message.
Enter names (optional) and the email address, such as Name <[email protected]>.
This parameter was introduced in PowerShell 6.2.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-SmtpServer
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 isn't set and this parameter isn't used, the Send-MailMessage command fails.
Parameter properties
| Type: | String |
| Default value: | $PSEmailServer |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | ComputerName |
Parameter sets
(All)
| Position: | 3 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-Subject
The Subject parameter isn't required. This parameter specifies the subject of the email message.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | sub |
Parameter sets
(All)
| Position: | 1 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-To
The To parameter is required. This parameter specifies the recipient's email address. Enter
names (optional) and the email address, such as Name <[email protected]>.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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 isn't used.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Inputs
String
You can pipe the path and file names of attachments to this cmdlet.
Outputs
None
This cmdlet returns no output.
Notes
The Send-MailMessage cmdlet is obsolete. For more information, see
Platform Compatibility note DE0005. This cmdlet doesn't guarantee
secure connections to SMTP servers.
DE0005 suggests using the third-party library, MailKit. If you are using Exchange Online, you can use the Send-MgUserMail from the Microsoft Graph PowerShell SDK.
