PowerShell

Using Send-MgUserMessage in Graph PowerShell

This guide explains how to use the Send-MgUserMessage cmdlet in Microsoft Graph PowerShell to send emails on behalf of a user. Learn how to compose messages, add recipients, and include attachments with practical examples

The Send-MgUserMessage cmdlet is a powerful Graph PowerShell command that allows administrators to send messages on behalf of users directly through Microsoft 365. It integrates deeply with the Microsoft Graph API to automate email tasks, making it useful for day-to-day operations like sending follow-up emails or distributing automated notifications.

In this article, we'll explore how to use the Send-MgUserMessage cmdlet with a detailed explanation of its syntax, practical usage examples, tips for its effective use, potential errors and their solutions, and real-world use cases. Let's dive in!

Cmdlet Syntax

Send-MgUserMessage -UserId <String> -MessageId <String>

Parameters:

UserId: The unique identifier (or UPN) of the user sending the message.
MessageId: The ID of the message that has been created using the New-MgUserMessage cmdlet or through another process.

Usage Examples

Example 1: Sending a Draft Email

In this example, we'll send an email message after creating it as a draft using the New-MgUserMessage cmdlet.

# Create the draft message
$draftMessage = @{
    subject = "Reminder: Upcoming Meeting"
    body = @{
        contentType = "HTML"
        content = "This is a reminder for your upcoming meeting scheduled for tomorrow at 10 AM."
    }
    toRecipients = @(@{ emailAddress = @{ address = "jane.doe@domain.com" } })
}

# Create the message and retrieve the MessageId
$message = New-MgUserMessage -UserId "john.doe@domain.com" -BodyParameter $draftMessage

# Send the message
Send-MgUserMessage -UserId "john.doe@domain.com" -MessageId $message.Id

Example 2: Sending a Follow-Up Email Automatically

This example demonstrates sending follow-up emails to multiple users after generating the messages.

# Create the follow-up draft message
$followUpMessage = @{
    subject = "Follow-Up: Action Required"
    body = @{
        contentType = "Text"
        content = "Please follow up on the task assigned to you."
    }
    toRecipients = @(@{ emailAddress = @{ address = "team.member@domain.com" } })
}

# Create and send the follow-up message
$message = New-MgUserMessage -UserId "manager@domain.com" -BodyParameter $followUpMessage
Send-MgUserMessage -UserId "manager@domain.com" -MessageId $message.Id

Example 3: Sending Bulk Notifications

Send bulk notifications to several users from a CSV file using this example:

# Read users from a CSV
$recipients = Import-Csv "recipients.csv"

foreach ($recipient in $recipients) {
    # Create draft for each user
    $notificationMessage = @{
        subject = "Important Update"
        body = @{
            contentType = "Text"
            content = "Please be informed about the recent updates to our policy."
        }
        toRecipients = @(@{ emailAddress = @{ address = $recipient.Email } })
    }

    # Create and send the message
    $message = New-MgUserMessage -UserId "admin@domain.com" -BodyParameter $notificationMessage
    Send-MgUserMessage -UserId "admin@domain.com" -MessageId $message.Id
}

CSV File Format


    Email
    jane.doe@domain.com
    john.smith@domain.com
    alice.brown@domain.com
    charles.jones@domain.com

Cmdlet Tips

Use Drafts Effectively: Always create the email as a draft using the New-MgUserMessage cmdlet before sending it using Send-MgUserMessage. This ensures that you can review and update the message if needed.
Check MessageId: The MessageId is crucial for this cmdlet to work. After creating a message, ensure that you store the MessageId properly to avoid errors when attempting to send it.
Bulk Emails: Automate repetitive email tasks by looping through a CSV or array of users, especially for notifications or updates.

Possible Errors & Solutions

Error	Cause	Solution
Missing Required Parameter MessageId	This happens when the MessageId parameter is not supplied.	Ensure that you are providing the correct MessageId after creating the draft message with New-MgUserMessage.
Invalid UserId	The UserId provided is incorrect or the user does not have permission to send emails.	Verify the UserId (it can be the user’s UPN or GUID) and ensure that the user exists and has the required permissions in the organization.
Message Not Found	The message associated with the MessageId has either been deleted or wasn’t created properly.	Ensure that the message was successfully created and that its MessageId is being correctly passed to the Send-MgUserMessage cmdlet.

Use Cases

Automating Follow-Up Emails: Administrators can automate the sending of follow-up emails to users after key events (e.g., project deadlines, meeting reminders). This ensures tasks stay on track without manual intervention.
Sending Bulk Notifications: Large organizations can use this cmdlet to send policy updates, system notifications, or important company announcements to all employees or specific groups.
Event Reminders: If you're managing event registrations, you can automate reminders to attendees using this cmdlet, reducing the manual workload while ensuring timely communication.

Frequently Asked Questions

1. What is Send-MgUserMessage used for?

Send-MgUserMessage is a Microsoft Graph PowerShell cmdlet used to send emails from a user’s mailbox, including options to specify recipients, subject, and body.

2. What permissions are required to send emails?

You need the Mail.Send or Mail.ReadWrite permission in Microsoft Graph PowerShell. Ensure these permissions are granted in Azure AD.

Conclusion

The Send-MgUserMessage cmdlet is a highly versatile tool for Microsoft 365 administrators, enabling seamless communication automation through PowerShell. By leveraging this cmdlet, administrators can simplify and enhance daily communication processes, ensuring timely follow-ups, notifications, and reminders without manual effort.

With its ability to scale across many users and its integration with the Microsoft Graph API, this cmdlet is a must-have for any admin’s toolkit. Make sure to explore its potential in automating your M365 communication tasks and don't forget to integrate proper error handling mechanisms to avoid common pitfalls.