Ship-MailMessage is out of date and now not supported. Microsoft says this cmdlet doesn’t assure a safe connection to SMTP servers. We are going to use Ship-MgUserMail.
This tutorial takes you thru utilizing Ship-MgUserMail to ship emails as an alternative of Ship-MailMessage
Utilizing Ship-MailMessage
Whenever you attempt to use the Ship-MailMessage cmdlet, you get the next warning.
WARNING: The command ‘Ship-MailMessage’ is out of date. This cmdlet doesn’t assure safe connections to SMTP servers. Whereas there isn’t any fast substitute accessible in PowerShell, we suggest you don’t use Ship-MailMessage at the moment. See https://aka.ms/SendMailMessage for extra info.
Ship-MailMessage doesn’t assist fashionable authentication. Suppose you’re utilizing Ship-MailMessage to ship emails by way of workplace 365. In that case, you’ll want to think about using a substitute cmdlet reminiscent of Ship-MgUserMail, as by October 1st, 2022, fundamental authentication received’t work anymore. However in case you are utilizing the Ship-MailMessage to ship emails by way of your native SMTP server, it’s nonetheless OK to make use of the cmdlet, however think about transferring to a supported technique.
Utilizing Ship-MgUserMail as a Substitute For Ship-MailMessage
This tutorial takes you thru the required parameter to construct all of the required parameters to ship emails utilizing Ship-MgUserMail with parameters to set the precedence degree talked about, BCC, CC, Flag, and extra.
In case you are new to graphs, check out Connecting and Understanding Microsoft Graph API Utilizing PowerShell additionally, you may test the Connect with Workplace 365 Utilizing Graph API and PowerShell for extra details about the way to configure Delegate and Utility authentication.
The very first thing is to know what are the required scope to make use of
(Discover-MgGraphCommand -Command Ship-MgUserMail -ApiVersion V1.0).PermissionsThe outcomes listing the next putout
Title IsAdmin Description FullDescription
---- ------- ----------- ---------------
Mail.Ship False Ship mail as you Permits the app to ship mail as you.So the one permission wanted is Mail.Ship
Ship-MgUserMail Fundamentals
In contrast to the Ship-MailMessage, the Ship-MgUserMail requires a extra complicated parameter construction. However no fear, all is defined right here. However however, the Ship-MgUserMail offers you entry to the complete SendMail endpoint, which helps all of the message parameters, reminiscent of Observe-up Flag, Significance, Reply to, mentions, Request learn and supply report and far far more options.
The endpoint the Ship-MgUserMail makes use of is:
[POST] https://graph.microsoft.com/v1.0/customers/USER_UPN/microsoft.graph.sendMailWe don’t want this info whereas writing the script, however it’s good to know the endpoints because it helps troubleshoot surprising points.
Ship-MgUserMail requires a BodyParameter parameter that features all of the mail parameter settings reminiscent of To, CC, Bcc.. and so forth.
Listed here are the parameters defined.
Not all of the parameters are obligatory.
Ship-MgUserMail BodyParameter Parameters
The Ship-MgUserMail parameters are easy, and an important one is the BodyParameter. The BodyParameter is a construction of hashtables and arrays, every one representing a parameter.
The cmdlet seems like the next.
Ship-MgUserMail -UserId 'Sender@EmailAddress.com' -BodyParameter $ParamsThe $Param variable is a hashtable that comprises all of the message parameter particulars. Let’s begin by explaining the small print and afterward see the whole code.
- Message: Hashtable comprises an inventory of parameters associated to the e-mail message. The Message might embody the next parameters.
- [Optional][String]Topic: The message topic.
- [Optional][Bool]isDeliveryReceiptRequested: Request Supply Report, the sender obtain a message reporting the supply standing,
- [Optional][Bool]isReadReceiptRequested: Request Recipient Learn Report
- [Optional][String]Significance: Can maintain Low, Regular, Excessive.
- [Optional][Hashtable]Physique: The message physique content material and may maintain the next keys and values
- [String]ContentType: HTML for wealthy textual content content material or Textual content for plain textual content content material.
- [String]Content material: For the precise physique content material, I like to make use of here-string for brief content material.
- [Optional][Array]ToRecipients: Include an inventory of hashtables. Every hashtable represents a recipient with the next keys and values. You possibly can add a number of EmailAddress hashtables for extra the one recipient.
- [Hashtable]EmailAddress
- Tackle=”To@Tackle.com”
- [Hashtable]EmailAddress
- [Optional][Array]CcRecipients: Much like ToRecipients
- [Optional][Array]BccRecipients: Much like ToRecipients
- [Optional][Array][BETA]Mentions: Embody an inventory of hashtables for customers to say. This seems within the consumer outlook as @. The Mentions comprise the next keys and values.
- [Hashtable]Talked about: embody the Title key for the talked about consumer
- Title=”Faris Malaeb”
- Tackle=”Myemail@PowerShellCenter.com”
- [Hashtable]Talked about: embody the Title key for the talked about consumer
- [Optional][Array]Attachments: an inventory of attachments to incorporate within the e-mail, every attachment represented in a hashtable. that comprise the next
- “@odata.sort” = “#microsoft.graph.fileAttachment”: Object Kind, Use it as is
- [String]Title: Path for the attachment
- [String]ContentType: The MIME sort of the hooked up file, for instance, “textual content/plain”
- [Base64String]ContentBytes: The attachment content material ought to be transformed to Base64String. You need to use the next line to transform the file [Convert]::ToBase64String([IO.File]::ReadAllBytes($AttachmentPath))
- [Optional][Hashtable]Flag: Include the follow-up flag standing. Ought to the message has a follow-up flag or not? It comprises the next Key and values.
- [Optional][Boolean]SaveToSentItems: If sure, the despatched message will likely be saved within the consumer despatched gadgets.
The ToRecipients, CcRecipients and BccRecipients are elective, however you have to use one. For instance, use the BccRecipients and skip the others. However aleast one recipient ought to be legitimate
It may not look as pleasant as Ship-MailMessage, however simply undergo the code, and you will discover it simple.
Right here is the whole code.
Import-Module Microsoft.Graph.Customers.Actions
$AttachmentPath="C:MyFile.txt"
$MyMessageContent=@'
<Robust> This can be a Check Message</Robust><br>
I Hope you prefer it
'@
$MessageAttachement = [Convert]::ToBase64String([IO.File]::ReadAllBytes($AttachmentPath))
$params = @{
Message = @{
Topic = "Lets Use Graph"
significance = "Low" #"Excessive"
isDeliveryReceiptRequested = "True"
isReadReceiptRequested = "True"
Physique = @{
ContentType = "html"
Content material = $MyMessageContent
}
ToRecipients = @(
@{
EmailAddress = @{
Tackle = "User1@E-mail.com"
}
}
@{
EmailAddress = @{
Tackle = "User2@E-mail.com"
}
}
)
CcRecipients = @(
@{
EmailAddress = @{
Tackle = "User3@E-mail.com"
}
}
)
BccRecipients = @(
@{
EmailAddress = @{
Tackle = "admin@e-mail.com"
}
}
)
Mentions = @( #BETA ONLY
@{
Talked about = @{
Title = "Faris Malaeb"
Tackle = "farismalaeb@powershellcenter.com"
}
}
)
Attachments = @(
@{
"@odata.sort" = "#microsoft.graph.fileAttachment"
Title = $AttachmentPath
ContentType = "textual content/plain"
ContentBytes = $MessageAttachement
}
)
Flag = @{
flagStatus="flagged"
}
}
SaveToSentItems = "false"
}
Join-MgGraph -Scopes Mail.Learn
Choose-MgProfile -Title beta
Ship-MgUserMail -UserId 'Sender@EmailAddress.com' -BodyParameter $paramsThe outcome seems like the next.
Ship-MgUserMail To Ship a Fundamental Message
$MyMessageContent=@'
<Robust> This can be a Check Message</Robust><br>
I Hope you prefer it
'@
$params = @{
Message = @{
Topic = "Lets Use Graph"
Physique = @{
ContentType = "html"
Content material = $MyMessageContent
}
ToRecipients = @(
@{
EmailAddress = @{
Tackle = "ToUser@Area.com"
}
}
)
}
}
Import-Module Microsoft.Graph.Customers.Actions
Join-MgGraph -Scopes Mail.Learn
Ship-MgUserMail -UserId 'Sender@PowerShellCenter.com' -BodyParameter $params
Ship E-mail Messages together with CC, Bcc.
$MyMessageContent=@'
<Robust> This can be a Check Message</Robust><br>
I Hope you prefer it
'@
$params = @{
Message = @{
Topic = "Lets Use Graph"
Physique = @{
ContentType = "html"
Content material = $MyMessageContent
}
ToRecipients = @(
@{
EmailAddress = @{
Tackle = "User1@powershellcenter.com"
}
}
)
CcRecipients = @(
@{
EmailAddress = @{
Tackle = "user2@powershellcenter.com"
}
}
)
BccRecipients = @(
@{
EmailAddress = @{
Tackle = "Bcc@powerShellcenter.com"
}
}
)
}
SaveToSentItems = "false"
}
Import-Module Microsoft.Graph.Customers.Actions
Join-MgGraph -Scopes Mail.Learn
Ship-MgUserMail -UserId 'Sender@powershellcenter.com' -BodyParameter $params
Ship E-mail Message with Attachment.
$AttachmentPath="C:MyFile.txt"
$MyMessageContent=@'
<Robust> This can be a Check Message</Robust><br>
I Hope you prefer it
'@
$MessageAttachement = [Convert]::ToBase64String([IO.File]::ReadAllBytes($AttachmentPath))
$params = @{
Message = @{
Topic = "Lets Use Graph"
Physique = @{
ContentType = "html"
Content material = $MyMessageContent
}
ToRecipients = @(
@{
EmailAddress = @{
Tackle = "ToUser@Area.com"
}
}
)
Attachments = @(
@{
"@odata.sort" = "#microsoft.graph.fileAttachment"
Title = $AttachmentPath
ContentType = "textual content/plain"
ContentBytes = $MessageAttachement
}
)
}
SaveToSentItems = "false"
}
Import-Module Microsoft.Graph.Customers.Actions
Join-MgGraph -Scopes Mail.Learn
Ship-MgUserMail -UserId 'Sender@powershellcenter.com' -BodyParameter $params
Ship E-mail With Excessive Precedence, Observe-up Flag, Supply Report, and Learn Report
$MyMessageContent=@'
<Robust> This can be a Check Message</Robust><br>
I Hope you prefer it
'@
$params = @{
Message = @{
Topic = "Lets Use Graph"
significance = "Excessive"
isDeliveryReceiptRequested = "True"
isReadReceiptRequested = "True"
Physique = @{
ContentType = "html"
Content material = $MyMessageContent
}
ToRecipients = @(
@{
EmailAddress = @{
Tackle = "TestUser@Area.com"
}
}
)
Flag = @{
flagStatus="flagged"
}
}
SaveToSentItems = "false"
}
Import-Module Microsoft.Graph.Customers.Actions
Join-MgGraph -Scopes Mail.Learn
Ship-MgUserMail -UserId 'faris@powershellcenter.com' -BodyParameter $params
Ship-MgUserMail with Mentions
$MyMessageContent=@'
<Robust> This can be a Check Message</Robust><br>
I Hope you prefer it
'@
$params = @{
Message = @{
Topic = "Lets Use Graph"
Physique = @{
ContentType = "html"
Content material = $MyMessageContent
}
ToRecipients = @(
@{
EmailAddress = @{
Tackle = "ToUser@Area.com"
}
}
)
Mentions = @( #BETA ONLY
@{
Talked about = @{
Title = "Faris Malaeb"
Tackle = "faris@powershellcenter.com"
}
}
)
}
SaveToSentItems = "false"
}
Import-Module Microsoft.Graph.Customers.Actions
Join-MgGraph -Scopes Mail.Learn
Choose-MgProfile -Title beta
Ship-MgUserMail -UserId 'faris@powershellcenter.com' -BodyParameter $params
Various Resolution
I wrote one other PowerShell script to simplify the method. The Ship-GraphMail can construct all the things for you and ship the e-mail if you need or simply return the JSON construction to your script to make use of elsewhere.
In the event you don’t need to undergo all these parameters, then check out PowerShell Script to Simplify Ship-MgUserMail submit.
Ultimate Although
I hope this clarifies why to make use of the Ship-MgUserMail as an alternative of Ship-MailMessage. the variety of supported parameters and choices is far more superior than the Ship-MailMessage and helps fashionable authentication. So, get able to replace your script.
If you wish to be taught extra on the way to substitute the present cmdlet you have got with a Graph API cmdlet, check out Migrate Your Script from AzureAD or MSOnline to Graph API
Kindly charge this submit should you prefer it 🙂
