PowerShell et Microsoft Graph : comment envoyer des e-mails avec Send-MgUserMail ?

I. Présentation

Dans ce tutoriel, nous allons utiliser PowerShell pour envoyer un e-mail avec la commande Send-MgUserMail de Microsoft Graph ! Cette commande représente une alternative à Send-MailMessage qui est considérée comme obsolète. Précédemment, nous avions vu comment utiliser MailKit pour envoyer des e-mails avec PowerShell (avec différents fournisseurs).

• PowerShell - Comment envoyer des e-mails avec MailKit ?

Si vous débutez avec Microsoft Graph, je vous recommande de lire les deux articles ci-dessous. Ils répondront surement à bon nombre de questions que vous pourriez vous poser !

• PowerShell : comment se connecter à Microsoft Graph API ?
• Microsoft Graph V2 - PowerShell : Nouveautés, migration V1/V2

II. Installer le module Microsoft Graph

Commençons par installer le module Microsoft Graph pour l'utilisateur actuel :

Install-Module Microsoft.Graph -Scope CurrentUser

Vous pouvez aussi l'installer pour tous les utilisateurs :

Install-Module Microsoft.Graph -Scope AllUsers

III. Application Microsoft Graph et l'autorisation Mail.Send

La seconde étape consiste à inscrire une nouvelle application sur votre tenant, à partir du portail Azure Active Directory (point d'entrée portal.azure.com).

Dans Azure Active Directory, cliquez sur "Inscriptions d'applications" à gauche puis sur le bouton "Nouvelle inscription".

Donnez un nom à cette application, par exemple "Script-PowerShell-Graph". Conserver l'option "Comptes dans cet annuaire d'organisation uniquement" pour l'option "Types de comptes pris en charge" et pour l'URI de redirection, laissez vide.

Cliquez sur le bouton "S'inscrire".

L'application est inscrite. Il y a deux informations qu'il faudra récupérer par la suite, car nous en aurons besoin lors de la connexion avec PowerShell : ID d'applications (client) et ID de l'annuaire (locataire).

Au sein de notre application, cliquez sur "API autorisées" à gauche puis au centre sur "Ajouter une autorisation" car nous devons donner l'autorisation à cette application pour qu'elle puisse utiliser le point d'entrée "Mail.Send".

Sélectionnez "Microsoft Graph" puis à l'étape suivante choisissez "Autorisations d'application".

Recherchez "mail.send" dans la zone de recherche, et cochez "Mail.Send" avant de valider. Cette autorisation permet d'envoyer un e-mail en tant que n'importe quel utilisateur !

L'autorisation vient s'ajouter à celle présente par défaut. Il reste à cliquer sur le bouton "Accorder un consentement d'administrateur pour Default Directory".

Les feux sont au vert. Vous devez obtenir ceci :

L'application Microsoft Graph pour PowerShell est prête ! Avec cette application, on a seulement l'autorisation d'envoyer des e-mails.

IV. Se connecter à Microsoft Graph avec un ClientSecretCredential

À partir de PowerShell, nous devons établir une connexion à Microsoft Graph grâce à l'application créée et configurée précédemment. Pour cela, on va commencer par définir trois variables :

# ID du tenant
$IDTenant = "806d3d28..."

# ID de l'application
$IDApp = "a8615473-....."

# Secret
$Secret = "<secret récupéré sur Azure>"

Vous disposez déjà de l'ID du tenant et de l'ID de l'application (informations récupérables dans la vue d'ensemble de l'application).

Pour le secret, que doit-on mettre ? Ceci va permettre de s'authentifier avec un secret (renouvelable) plutôt qu'avec un certificat. Ceci rend l'authentification transparente, ce qui est idéal pour un script qui doit tourner en tâche planifiée, par exemple.

À partir du portail Azure, dans l'application, cliquez sur "Certificats & secrets" à gauche, puis sur l'onglet "Secrets client" afin de cliquer sur "Nouveau secret client". Sur la droite, on va vous demander une description et une date d'expiration. La valeur recommandée par Microsoft est 6 mois, mais c'est personnalisable.

Cliquez sur "Ajouter" : votre secret sera visible !

Vous devez copier la valeur et l'utiliser pour la variable $Secret :

# Secret
$Secret = "LT18Q...."

Il ne reste plus qu'à utiliser ces trois informations pour établir la connexion à Microsoft Graph :

$SecureSecret = ConvertTo-SecureString -AsPlainText $Secret -Force
$ClientSecretCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList ($IDApp, $SecureSecret)
Connect-MgGraph -TenantId $IDTenant -ClientSecretCredential $ClientSecretCredential

Si la connexion est réussie, le message de bienvenue s'affiche !

Welcome to Microsoft Graph!

Si vous préférez utiliser le mode interactif afin que le secret soit demandé (il faudra le copier-coller pour valider la connexion), utilisez cette syntaxe :

$ClientCredential = Get-Credential -Username $IDApp -Message "Indiquez le secret"
Connect-MgGraph -TenantId $IDTenant -ClientSecretCredential $ClientCredential

La connexion est établie, passons à la suite !

V. Envoyer un e-mail avec Send-MgUserMail

Le module est installé. L'application est prête sur notre tenant. Dernière étape à réaliser : envoyer un e-mail avec Send-MgUserMail !

• Microsoft Learn - Send-MgUserMail

Commençons par définir un ensemble de variables pour préciser le serveur SMTP, le numéro de port, l'objet de l'e-mail, l'expéditeur, etc... Il est à noter que l'expéditeur doit exister sur votre tenant ! Vous ne pouvez pas mettre n'importe quoi.

# SMTP : Serveur
$SMTPServer = "smtp.office365.com"

# SMTP : Port
$SMTPPort = 587

# SMTP : Expéditeur
$SMTPSender = "[email protected]"

# E-mail : objet
$EmailSubject = "E-mail envoyé avec Microsoft Graph"

# E-mail : corps
$EmailBody = "<h1>Démo Microsoft Graph</h1>"

# SMTP : Destinataire(s)
$SMTPRecipient = "[email protected]"

$SMTPRecipientList = @()
$SMTPRecipientList += @{
      EmailAddress = @{
         Address = $SMTPRecipient
   }
}

Puis, on détermine les propriétés de notre e-mail, à l'aide des valeurs définies ci-dessus.

$EmailProperties = @{
   ToRecipients = $SMTPRecipientList
   Subject = $EmailSubject
   Body = @{
      ContentType = "HTML"
      Content = $EmailBody
   }
}

Il ne reste plus qu'à envoyer l'e-mail avec Send-MgUserMail ! Ce qui donne :

Send-MgUserMail -UserId $SMTPSender -Message $EmailProperties

Quelques secondes plus tard, j'ai bien reçu l'e-mail dans ma boite aux lettres !

Une fois les e-mails envoyés, pensez à vous déconnecter de Microsoft Graph :

Disconnect-MgGraph

VI. Conclusion

Désormais, vous êtes capable d'envoyer un e-mail en PowerShell en passant par Microsoft 365 et l'API Microsoft Graph ! Cet e-mail est envoyé de manière sécurisée, sans avoir besoin d'exposer les identifiants d'un utilisateur et avec des droits limités. Si vous avez besoin d'envoyer un e-mail en utilisant un autre service que Microsoft 365, pensez à regarder mon article basé sur PowerShell et MailKit (lien en introduction).

Florian BURNEL Co-founder of IT-Connect

Ingénieur système et réseau, cofondateur d'IT-Connect et Microsoft MVP "Cloud and Datacenter Management". Je souhaite partager mon expérience et mes découvertes au travers de mes articles. Généraliste avec une attirance particulière pour les solutions Microsoft et le scripting. Bonne lecture.

See Full Bio