Using Send-MgUserMail to send emails in Powershell

We all know that effective communication is crucial, and email remains vital for professional interactions. For administrators and developers using Microsoft 365, automating email notifications, reports, and alerts is not just convenient but essential.

Today, we’ll explore Send-MgUserMail to understand its capabilities, applications, and best practices, including sending emails using this cmdlet.

Join us as we uncover the potential of Send-MgUserMail and how it can empower your organization's email automation strategy.

What Is the Send-MgUserMail Cmdelt?

Send-MgUserMail is a command in the Microsoft Graph PowerShell SDK, used to send emails on behalf of a Microsoft 365 user (similar to the Send-EmailMessage cmdlet in PowerShell Utility). It allows administrators and developers to automate the process of sending emails through scripts by leveraging Microsoft Graph API endpoints. This command requires appropriate permissions, such as Mail.Send, for the user whose mailbox is being accessed.

It's part of a broader suite of tools provided by Microsoft Graph to manage and interact with Microsoft 365 services programmatically, offering flexibility in handling tasks like user and group management, calendar events, and more, directly from the command line or scripts.

Here’s the syntax of the Send-MgUserMail cmdlet and the meaning of each of its parameters:

• -UserId <String>: Specifies the user ID of the mailbox from which the email will be sent.
• -ResponseHeadersVariable <String>: Stores the HTTP response headers from the request in the specified variable.
• -AdditionalProperties <Hashtable>: Allows you to specify additional properties as a hashtable to be included in the request.
• -Message <IMicrosoftGraphMessage>: Defines the email message to be sent, including details such as recipients, subject, body, and attachments.
• -SaveToSentItems: Indicates whether the sent email should be saved to the user's Sent Items folder.
• -Headers <IDictionary>: Specifies custom HTTP headers to include in the request.
• -PassThru: Returns the created or modified object for further use in the pipeline.
• -ProgressAction <ActionPreference>: Specifies how progress is displayed to the user.
• -WhatIf: Shows what would happen if the command runs, without actually executing it.
• -Confirm: Prompts for confirmation before executing the command.

What Can You Use the Send-MgUserMail Command For?

The Send-MgUserMail command can be used for several purposes in managing and automating email tasks within Microsoft 365 environments, such as the following:

1. Automated Notifications and Alerts: Organizations often need to send automated notifications and alerts to users or administrators. Using Send-MgUserMail, you can script notifications for events such as system downtime, scheduled maintenance, or critical security alerts.
2. Scheduled Reports and Status Updates: IT administrators often need to send scheduled reports or status updates to management or team members. With Send-MgUserMail, you can schedule PowerShell scripts to generate reports and email them automatically.
3. User Provisioning and Onboarding: During user onboarding or provisioning processes, it's common to send welcome emails, setup instructions, and policy reminders. Send-MgUserMail can be integrated into scripts to automate these communications, reducing manual effort and ensuring consistency.

Prerequisites to Run the Send-MgUserMail Command

If you want to run Send-MgUserMail without inconvenience, it’s important to comply with these prerequisites:

1. Microsoft Graph Version 2.0 or higher: Make sure you have Microsoft Graph version 2.0 or higher installed to use the new parameters and functionality provided by the command.

2. Authentication and Permissions: There are a few permissions you’ll need in order to run this command, which, according to Microsoft’s website, include the following:

• Delegated Permissions (Work or School Account): You need the Mail.Send permission, which allows the script to send emails on behalf of the signed-in user.
• Delegated Permissions (Personal Microsoft Account): Similar to work or school accounts, you need the Mail.Send permission.
• Application Permissions: Currently, application permissions are not available for sending emails using this command.

3. Email Format: You can send the message specified in the request body using either JSON or MIME format. When using JSON format, you can include a file attachment in the same sendMail action call. When using MIME format, the method saves the message in the Sent Items folder. You can also create a draft message to send later.

How to Use Send-MgUserMail to Send Emails in PowerShell

Now, in order to start email messaging within PowerShell using this command, follow these quick three steps.

Step 1: Install Microsoft Graph PowerShell SDK

Before you can use the Send-MgUserMail command, you need to install the Microsoft Graph PowerShell SDK if it's not already installed. This SDK provides cmdlets that enable you to interact with Microsoft 365 services, including sending emails through Microsoft Graph APIs.

To install the Microsoft Graph PowerShell SDK, run this command on PowerShell:

After installation completes, you can verify that the module is installed by listing all installed modules using this command:

Step 2: Authenticate and Obtain Permissions

Now, before we can send emails using the Send-MgUserMail command, you need to authenticate to Microsoft Graph and obtain the necessary permissions.

Run the following command to initiate the authentication process and request the necessary Mail.Send permission:

This command will prompt you to sign in using your Microsoft 365 account credentials and grant the required permissions.

Step 3: Send an Email by Executing the Command

Now that you have installed the SDK, authenticated, and obtained the necessary permissions, you can use the Send-MgUserMail command to send an email.

Take a look at the following example:

This command sends a basic email with the subject "Go for a walk?", and the body "Let’s walk by the park in an hour!" to simon@meetingroom365.com. Additionally, it sends a copy of the email to james@meetingroom365.com, and does not save the email to the Sent Items folder.

By following these steps, you can effectively use the Send-MgUserMail command to send emails programmatically in your Microsoft 365 environment using PowerShell. Keep in mind that the emails can be further modified according to your needs, including changing the list of recipients, identifiers, and more.

Sending Emails with Send-MgUserMail in PowerShell

Send-MgUserMail from the Microsoft Graph PowerShell SDK is a versatile tool that allows administrators and developers to automate email communication effectively within Microsoft 365 environments.

Whether you're automating notifications, delivering scheduled reports, or facilitating user onboarding, Send-MgUserMail offers the flexibility and reliability needed to meet diverse business needs.