About

This module provides a PowerShell wrapper around Microsoft Graph's Mail API. It is designed to be a lightweight and easy-to-use tool for interacting with Microsoft Graph's Mail API. It is not designed to be a full-featured mail library, but rather a tool for automating common tasks.

Installing

This module is published to the PowerShell Gallery. You can install it using the following command:

Install-Module -Name MSGraphMail

From time-to-time, preview releases will be published to the PowerShell Gallery. These are not considered stable and should not be used in production. You can install preview releases using the following command:

Install-Module -Name MSGraphMail -AllowPrerelease

Getting Started

The first and probably most important requirement for this module is getting it connected to Microsoft Graph.

Creating an application in Microsoft Entra ID (Azure AD)

Rather than attempting to maintain documentation on how to create an application in Microsoft Entra ID (Azure AD), please refer to the official documentation for creating an application in Microsoft Entra ID (Azure AD).

You should ensure your application has the appropriate scopes for the operations you wish to perform. For example, if you wish to send mail on behalf of a user, you will need to ensure your application has the Mail.Send scope. If you wish to read mail on behalf of a user, you will need to ensure your application has the Mail.Read scope. You can find a full list of scopes here. You can also find a list of permissions required for each operation in the commandlet documentation.

Connecting to the Microsoft Graph API

Connecting to the Microsoft Graph API uses the Azure AD Application information and the Connect-MSGraphMail client application.

Using the Splatting technique:

Splatting is a system in PowerShell that lets us put our parameters in a nicely formatted easy to read object (a HashTable to be specific!) and then "splat" them at the command. To do this, first things first setup a PowerShell object to hold your credentials. For example:

$MSGraphMailConnectionParameters = @{
    ApplicationID = '<YOUR APPLICATION ID>'
    ApplicationSecret = '<YOUR APPLICATION SECRET>'
    TenantID = '<YOUR TENANT ID>'
}
Connect-MSGraphMail @MSGraphMailConnectionParameters

Using the Traditional technique:

If you don't want to - or can't "splat" - we can fall back on a more traditional route:

Connect-MSGraphMail -ApplicationID '<YOUR APPLICATION ID>' -ApplicationSecret '<YOUR APPLICATION SECRET>' -TenantID '<YOUR TENANT ID>'

For more information on the Connect-MSGraphMail commandlet, please see the documentation.

Examples

Check the examples documentation for detailed examples of how to use this module.

Known Issues

Known issues will be tracked in the GitHub issue tracker. If you find a bug, please open an issue.