发送电子邮件的四种方式 PowerShell 和 Microsoft Graph

微软提供原始 API 和两种 SDK 方法

SMTP AUTH 仍然是支持基本身份验证的 Exchange Online 连接协议。微软被迫将其从处于退役最后阶段的协议集中排除。太多组织拥有太多通过 Exchange Online 发送电子邮件的设备和应用程序，导致 Microsoft 无法停止 SMTP AUTH。然而，毫无疑问这将会发生。唯一的问题是什么时候。

替代方法是使用 Microsoft Graph API 创建和发送电子邮件。在过去一年左右的时间里，我一直在研究可用的方法。 Microsoft 提供以下基于图形的选项：

• 图 sendMail API。
• Microsoft Graph PowerShell SDK 中的 Send-MgUserMessage cmdlet。
• Microsoft Graph PowerShell SDK 中的 Send-MgUserMail cmdlet。

为什么 Microsoft Graph PowerShell SDK 包含两种完成相同工作的方法？答案之一在于 Microsoft 使用 AutoRest 进程自动生成 SDK cmdlet 的方式。如果存在 API，SDK 会获取一个 cmdlet。由于 Graph 包含 message: send API 和 user: sendMail API，因此 SDK 的两个 cmdlet 都通过 Exchange Online 发送电子邮件。但更重要的是，每个 cmdlet 都有不同的用途。我们很快就会谈到这一点。

独立的 Send-EmailMessage cmdlet

如果您不喜欢 Microsoft 的 cmdlet，Przemyslaw Klys（备受推崇的 PSWriteHTML PowerShell 模块的开发人员）在 Send-EmailMessage cmdlet 中提供了他自己对该主题的看法。该 cmdlet 位于名称精美的 Mailozaurr 模块中。

与 Microsoft Graph PowerShell SDK cmdlet 不同，Przemyslaw 的工作展示了一些深思熟虑的编程的特点，使创建和发送消息尽可能容易。例如，Microsoft 的 cmdlet 需要对大型附件（超过 3 MB 的附件）进行特殊处理，这可能是一个真正的障碍（请参阅 MVP Glen Scales 撰写的这篇文章）。 Send-EmailMessage cmdlet 自动处理大型附件，这正是 Microsoft cmdlet 应该做的事情。

人们之所以使用微软的API，是因为它们就是微软的API。尽管可能存在更好的独立替代方案，但组织可能不愿意基于未正式支持的模块编写代码。当然，内部开发人员可以完全按照 Przemyslaw 所做的那样，围绕 Graph API 构建更好的包装器，但我看不到很多人急于这样做。无论如何，请查看 Mailozaurr 模块并做出自己的决定。

在两个 SDK Cmdlet 之间做出选择

如果要在两个 SDK cmdlet 之间进行选择，您应该使用哪一个？之前，我介绍了如何使用 Send-MgUserMessage cmdlet 发送电子邮件。 Send-MgUserMail cmdlet 更易于使用，因为您可以使用单个命令创建和发送消息，而不是先创建草稿消息（使用 New-MgUserMessage）然后再创建发送它。

就其本身而言，在一个动作中创建和发送可能使 Send-MgUserMail 在应用程序需要发送电子邮件的大多数情况下成为一个不错的选择。通常，这些消息类似于通知，让某人了解某些信息，例如作业完成或需要检查的内容（例如权限较高的 Azure AD 应用程序）。

Send-MgUserMessage 确实有一些技巧。由于它发送已创建的消息，因此它可以处理回复和消息转发等场景。但是，我认为相对较少的应用程序需要处理草稿消息或响应入站邮件，此功能可能不像看起来那么有用。

测试 Send-MgUserMail

为了测试使用 Send-MgUserMail cmdlet 的容易程度，我转换了与 Send-MgUserMessage 一起使用的示例脚本。该脚本向新员工发送欢迎消息。它使用 Get-ExoMailbox cmdlet 查找上周创建的邮箱。这是合乎逻辑的，因为如果我们要发送欢迎消息，它需要发送到邮箱。如果您不想加载 Exchange Online 管理模块，可以执行类似的操作：

$CheckDate = (Get-Date).AddDays(-7)
[array]$Users = Get-MgUser -All -Filter "userType eq 'Member'"
$Users = $Users | Where-Object {$_.CreatedDateTime -gt $CheckDate}

该命令运行得非常好，但它的性能在较大的租户中不会表现出色。 Get-MgUser cmdlet 不支持根据帐户的创建日期进行过滤，因此要查找最近创建的帐户集，我们必须获取所有帐户，然后应用客户端过滤器。相比之下，Get-ExoMailbox cmdlet 可以愉快地使用服务器端筛选器，这意味着 Exchange Online 仅返回目标邮箱集。

[array]$Users = (Get-ExoMailbox -Filter "WhenMailboxCreated -gt '$CheckDate'" -RecipientTypeDetails UserMailbox -ResultSize Unlimited -Properties WhenMailboxCreated | Select WhenMailboxCreated, DisplayName, UserPrincipalName, PrimarySmtpAddress)

当我写到 Send-MgUserMessage 时，我注意到 cmdlet 使用数组来传递消息的收件人，并表示 SDK 开发人员可以通过使构建消息属性的这一部分变得更容易来帮助我们所有人。 PowerShell 函数可以解决这个问题，可以处理“收件人”、“抄送”和“密件抄送”收件人。

Function Populate-MessageRecipient { # Build a list of recipients for a message
    [cmdletbinding()]
    Param(
        [array]$ListOfAddresses )
    ForEach ($SMTPAddress in $ListOfAddresses) {
        @{
            emailAddress = @{address = $SMTPAddress}
        }    
    }    
}

为了添加收件人，我们创建一个数组来保存每个收件人的 SMTP 地址，并将其通过函数创建数组以添加到消息属性中。例如，此代码添加两个收件人（通讯组和邮箱）作为抄送收件人。

$CcRecipientList = @( 
        '[email protected]'
        '[email protected]' )
[array]$MsgCcRecipients = Populate-MessageRecipient -ListOfAddresses $CcRecipientList

脚本的其余部分：

• 准备以 Base64 编码的附件。
• 为收件人自定义消息内容并构建 HTML 消息正文。
• 填充邮件属性集（主题、收件人、抄送收件人、附件和邮件正文）。
• 填充两个消息参数（将消息保存到已发送项目并要求提供送达回执）。
• 使用 Send-MgUserMail 发送消息。

代码如下（完整脚本可从 GitHub 获取）：

$MsgAttachment = @(
	@{
	"@odata.type" = "#microsoft.graph.fileAttachment"
	Name = ($AttachmentFile -split '\')[-1]
	ContentType = "text/plain"
	ContentBytes = $EncodedAttachmentFile
	} 
)

ForEach ($User in $Users) {
  $ToRecipientList   = @( $User.PrimarySmtpAddress )
  [array]$MsgToRecipients = Populate-MessageRecipient -ListOfAddresses $ToRecipientList
  Write-Host "Sending welcome email to" $User.DisplayName
  # Customize the message 
  $htmlHeaderUser = "<h2>New User " + $User.DisplayName + "</h2>"    
  $HtmlMsg = "</body></html>" + $HtmlHead + $htmlheaderuser + $htmlbody + "<p>"
  # Construct the message body
  $MsgBody = @{
     Content = "$($HtmlMsg)"
     ContentType = 'html'   }

  $Message =  @{subject           = $MsgSubject}
  $Message += @{toRecipients      = $MsgToRecipients}  
  $Message += @{ccRecipients      = $MsgCcRecipients}  
  $Message += @{attachments       = $MsgAttachment}
  $Message += @{body              = $MsgBody}
  $Params   = @{'message'         = $Message}
  $Params  += @{'saveToSentItems' = $True}
  $Params  += @{'isDeliveryReceiptRequested' = $True}

  Send-MgUserMail -UserId $MsgFrom -BodyParameter $Params
}
Write-Host "All done. Messages sent!"

一切正常，我们的新员工收到了良好的欢迎信息（图 1）。

处理权限

使用 Send-MgUserMessage 和 Send-MgUserMail cmdlet 都需要 Mail.Send Graph 权限。创建要发送的 Send-MgUserMessage 草稿消息需要 Mail.ReadWrite 权限。这些权限适用于租户中的每个邮箱。换句话说，配备这些权限并使用基于证书的身份验证的后台应用程序可以写入每个邮箱并从每个邮箱发送电子邮件。对于此类访问，必须注意限制与应用一起运行的脚本或使用 Azure 自动化 Runbook（无论是否有托管标识）访问邮箱的能力。

正确的方法是使用应用程序访问策略。这些策略规定了应用程序可以访问的邮箱，这意味着您可以将应用程序限制为某些特定于应用程序的邮箱，并使它们远离用户邮箱。

决策时间

有选择真是太好了。更新脚本以消除对 SMTP AUTH 依赖的开发人员至少有四个基于图形的选项。对我来说，我认为我应该尽可能使用 Send-MgUserMail，因为这是发送消息的最简单方法。至少，是最简单的基于 Microsoft 的方法。独立的 Send-EmailMessage cmdlet 看起来也是一个有吸引力的选择！